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 publisher’s engineering team through getting a working Publisher Commerce sandbox. The mechanics mirror the destination-side sandbox setup in For Destinations → Sandbox Setup — Publisher Commerce adds the wrinkle of testing the CMS embed format end-to-end.

​​ 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 test merchant domain — typically staging.luma.gift with a non-empty catalog of products
  3. Optional: server-to-server secret — if your publisher backend pre-renders Buy Now button data

​​ 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 Publisher Commerce-specific flows:

​​ CMS embed smoke-test

  1. Author a test article in your CMS with a Buy Now button embed pointing at a sandbox SKU
  2. Render the article in your staging environment
  3. Confirm the button renders correctly — image, price, and click-handler all wired up. Where the button sources its image and price (fetched by the component vs. supplied in the embed) depends on the embed format Firmly provides during onboarding — confirm the source with your Firmly contact if the values are missing
  4. Click Buy Now — slide-in panel opens with cart pre-populated
  5. Run a test purchase — use the sandbox test card from For Destinations → Sandbox Setup, confirm cart_status === "submitted"
  6. Confirm article identifier in order metadata — the test merchant’s order metadata should include the publisher ID + article ID

​​ Multi-product article smoke-test (for roundup articles)

  1. Author a test roundup article with 3+ Buy Now buttons for different products from the same test merchant
  2. Click Buy on multiple products — confirm cart badge increments
  3. Open the cart panel — verify all items present with correct quantities
  4. Complete checkout — confirm a single order is placed with all line items

​​ Sticky-cart smoke-test

  1. Scroll deep into a long article — confirm cart badge stays visible (sticky behavior)
  2. Add an item, close the panel — cart badge persists
  3. Open the panel later in the same session — items still in cart
  4. Navigate to a different article (same publisher) — confirm whether cart persists per your publisher’s chosen policy

​​ Common setup issues

Symptom Likely cause Fix
Buy Now button doesn’t render CMS embed format mismatch Confirm the embed shortcode matches the format Firmly’s component expects
401 on browser-session Sandbox App ID not loaded into the embed Confirm the embed reads sandbox App ID, not production
Multiple Buy Now clicks bootstrap separate sessions Each click creates a new session Audit session-persistence logic; reuse the existing token across clicks
Article ID missing from order metadata Article context not attached to the cart session (the cart is created implicitly by the first POST /cart/line-items; the article ID must be set on the session so it rides through to complete-order) Audit where the article ID is sourced and how it’s attached to the cart session — the exact carrier field is confirmed with Firmly during onboarding

​​ CMS-specific notes

CMS type Common gotcha
Block-based CMS Buy Now block may not render in the CMS’s visual preview — test in front-end render only
Structured / headless CMS Custom block needs explicit data mapping to the Firmly embed config
Custom CMS Sandbox testing requires a staging environment; don’t test on production article URLs

​​ 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 feature in articles — production App IDs are scoped to specific merchants
  3. Update CMS embed config to point at production App ID
  4. Plan a soft launch with a small set of articles before broad rollout
  5. Run the Going Live checklist for universal launch concerns