Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Solutions
  3. ...
  4. Operations
  5. Sandbox Setup

Sandbox Setup

This page walks the operator’s engineering team through getting a working Marketplace sandbox. The mechanics mirror the destination-side sandbox setup in For Destinations → Sandbox Setup — Marketplace adds the wrinkle of wanting several test merchants so search-across-merchants (discovery) can be exercised.

​​ What you need from Firmly

Contact Firmly to request sandbox access, and you’ll receive:

  1. A sandbox App ID (_appId) — a UUID scoped to a non-production environment
  2. A few test merchant pairings — 2–3 diverse test merchant domains so discovery across merchants can be exercised
  3. Optional: server-to-server secret — if your operator backend acts as a marketplace-level orchestrator

Tell Firmly the kind of catalog you need to test — different product categories, shipping zones, payment options — so the test merchants are diverse enough to surface real edge cases.

​​ Endpoints

Surface Host
General API (auth, discovery, cart, checkout) https://api.firmly.work
Payment (key, place-order) https://cc.firmly.work

​​ Smoke-test the integration

Once you have your sandbox credentials, run the basic three calls from For Destinations → Sandbox Setup to confirm auth, discovery, and the payment key work.

Then verify the Marketplace flows:

​​ Discovery across merchants

  1. Search without a merchant filter — POST /api/v1/discovery/search should return products spanning your test merchants, each with its source domain
  2. Confirm merchant identity — each result carries the source merchant so your UI can label listings

​​ Single-merchant checkout

  1. Add 2 items from one test merchant — POST /cart/line-items twice, scoped to that merchant’s {domain}
  2. Set shipping + payment + complete order — confirm cart_status === "submitted"
  3. Verify the order landed — the operator ID should be in the order metadata. Operators don’t have direct access to a test merchant’s OMS, so verify via the complete-order response (cart_id, custom_properties) and the Destination Dashboard, or ask your Firmly contact to confirm the order and its metadata in the test merchant’s OMS

​​ Common setup issues

Symptom Likely cause Fix
401 on browser-session Sandbox App ID not loaded Confirm operator code reads sandbox App ID, not production
Search returns one merchant only Discovery call filtered to a single merchant, or only one test merchant provisioned Remove the filter; ask Firmly for more test merchants
Cart add rejected POST /cart/line-items not scoped to the item’s source merchant {domain} Audit cart-add logic
Shipping methods missing Reading methods from get-availability (it doesn’t return them), or not walking every shipment Read shipping_method_options from each cart.shipments[] entry (populated by set-shipping-info), not just the first

​​ Going live

When the sandbox flow looks healthy end-to-end:

  1. Request a production App ID from Firmly
  2. Confirm the production merchants you’ll aggregate — production App IDs are scoped to specific merchants
  3. Start with a small set of merchants you’ve tested with extensively
  4. Run the Going Live checklist for universal launch concerns