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 destination engineer through getting a working Ad Commerce sandbox. The mechanics mirror the destination-side sandbox setup in For Destinations → Sandbox Setup — Ad Commerce uses the same App ID + test merchant pairing as every other solution.

​​ What you need from Firmly

Contact Firmly and ask for:

  1. A sandbox App ID (_appId) — a UUID scoped to a non-production environment
  2. A test merchant domain — typically something like staging.luma.gift, with a non-empty catalog you can advertise against
  3. Ad-platform sandbox account (if applicable) — Meta Ads sandbox, Google Ads test campaign, etc. — set up separately on the ad platform’s side

Firmly issues:

  • Sandbox App ID
  • Test merchant pairing
  • Optional server-to-server secret if needed for backend creative serving

​​ 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 three calls from For Destinations → Sandbox Setup to confirm auth, discovery, and the payment key work.

Then verify the Ad Commerce flow end-to-end:

  1. Render a test ad creative — point it at a sandbox SKU from the test merchant catalog
  2. Click through — the ad’s click should hit your landing or in-ad surface
  3. Confirm click-ID capture — your landing/creative should parse the click-ID parameter from the click URL
  4. Run a sandbox purchase — use a test card (4111111111111111) and confirm cart_status === "submitted"
  5. Confirm the order landed — the order should carry the click-ID in its metadata. Destinations don’t have direct access to the test merchant’s OMS, so verify via the order-placement response (cart_id, custom_properties) and the Destination Dashboard, or ask your Firmly contact to confirm the order in the test merchant’s OMS

​​ Ad-platform sandbox setup

Set this up separately on the ad platform’s side:

  • Meta — Meta Business Manager has a sandbox/test mode for ad accounts; create a test campaign that doesn’t spend real ad budget
  • Google Ads — use Google Ads Test Accounts for end-to-end ad serving without billing
  • TikTok — TikTok Marketing API has a sandbox endpoint for testing creative + conversion tracking
  • Other ad platforms — see the platform’s developer documentation for sandbox details

Wire the ad-platform sandbox to your Firmly sandbox App ID so end-to-end tests don’t touch production data on either side.

​​ Common setup issues

Symptom Likely cause Fix
401 on browser-session Sandbox App ID not loaded into the creative Confirm the creative is reading the sandbox App ID, not production
Empty products array on discovery/search Test merchant has no products Ask Firmly to load sample products into the test merchant
Click-ID missing from order metadata Click-ID not persisted between click and complete-order Audit your cart-session persistence logic
Conversion postback firing on impression Postback wired to the wrong event Move postback to fire on cart_status === "submitted"

​​ Going live

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

  1. Request a production App ID from Firmly
  2. Confirm the live merchants you’ll advertise against — production App IDs are scoped to specific merchants
  3. Move your ad-platform setup from sandbox to production
  4. Switch from test cards to real cards — test card numbers are rejected in production, which accepts real cards and wallet payments
  5. Run the Going Live checklist for the universal launch concerns