Onboarding

Firmly onboards each destination directly. You get an App ID paired with a test merchant, scoped to your environment, so your first call works straight away. The flow is short — most destinations are live in sandbox within one business day of the initial request — but every App ID is issued deliberately so that environment scope, merchant pairing, and per-destination configuration are correct before the first call.

This page walks the full path. For the abbreviated version, see Advanced Checkout Guide.

​​ The 4 phases at a glance

​​ Phase 1 — Sandbox provisioning

You contact Firmly with a short brief. Useful details to include:

• Destination type — AI agent, publisher, ad platform, marketplace operator, brand partner
• Integration shape — hosted checkout, embedded checkout, full Cart API, headless SDK
• Target launch surface — what users will see (a chat assistant, an article page, a creative unit, a marketplace UI)
• Solution — Agentic Commerce, Publisher Commerce, Ad Commerce, Marketplace, Branded Commerce
• Tech stack — language, runtime, where the integration code will live

Firmly issues:

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 search and buy from
3. Optional: a server-to-server secret — if you plan to use S2S auth instead of browser sessions

The sandbox App ID + test merchant pair is the gate. Until you have both, no API call will return data — /discovery/search and /cart/* are scoped to the merchants your App ID is approved to transact against.

​​ Phase 2 — Sandbox integration

This is where you write the code. The full surface area is in the API Reference. Most integrations follow this rough sequence:

1. Bootstrap auth — see Authentication
2. Discover products — POST /api/v1/discovery/search
3. Add to cart — POST /api/v2/domains/{domain}/cart/line-items
4. Set shipping address — POST /api/v2/domains/{domain}/cart/shipping-info
5. Set shipping method — POST /api/v2/domains/{domain}/cart/shipment/methods
6. Encrypt card and complete order — POST /api/v2/payment/domains/{domain}/complete-order (finalizes the cart built in steps 3–5; place-order is the one-shot alternative that creates the cart and places the order in a single call)

For a runnable end-to-end example, see Advanced Checkout Guide (~150 lines of Node).

The sandbox accepts test cards (4111111111111111, etc.) — see Sandbox setup for the full list. These cards only work against test merchants; real merchants reject them.

​​ What you build during sandbox

​​ Phase 3 — Pre-launch review

Once your sandbox integration is feature-complete, schedule a pre-launch review with Firmly. The review covers:

• Integration walkthrough — how your code flows from user intent to placed order
• Error handling — how you handle merchant declines, payment failures, network issues
• Idempotency — are you guarding against duplicate mutations? Re-read cart_status before retrying complete-order/place-order. (Idempotency-Key is honored on the UCP bridge; core REST doesn’t deduplicate on it today.)
• Rate-limit posture — are you throttling appropriately for production traffic
• Observability — what you’ll log for debugging and reconciliation
• Production merchants — which merchants you’ll transact against in production

This is not a hard gate — it is a structured review. If items need to be addressed, the destination addresses them and Firmly re-reviews the relevant parts.

​​ Phase 4 — Production App ID

After the review, Firmly issues:

1. A production App ID — a separate UUID, distinct from your sandbox App ID
2. Production merchant scope — the live merchants your App ID is approved to transact against
3. Base URLs — production runs on different hosts from the sandbox. Firmly provides them at go-live, so treat the cutover as a configuration change, not just a new App ID.

There’s no separate “production SDK” or library swap. Same code, different App ID, real merchants.

​​ What changes between sandbox and production

​​ What Firmly does not provide

• No self-serve App ID provisioning — every App ID is issued manually by Firmly, and scope changes go through Firmly; there’s no form that generates or rescopes one yourself. App ID requests come through Firmly.
• No SDK in 10 languages — Firmly publishes endpoint contracts plus examples in cURL and TypeScript; integration happens at the destination’s HTTP layer

This is intentional. Destination integration is lightweight on Firmly’s tooling side — the heavy lifting (merchant adapters, payment routing, order placement) runs on Firmly’s servers, not in a client library.

​​ The Destination Dashboard

Once Firmly provisions your App ID, it invites your team by email to the Destination Dashboard — the surface you sign into to run your integration day-to-day. It’s a single shared surface across all five solution types (agentic, branded, publisher, ad, marketplace), keyed on your App ID.

From the dashboard you track your conversion funnel, review orders, see the merchants you can reach, manage your team with role-based access, and read audit logs. App ID provisioning and merchant scope stay with Firmly — the dashboard is for operating and team management, not self-serve credential issuance.

See Destination Dashboard for the full reference.

​​ Related

• Advanced Checkout Guide — runnable end-to-end example
• Authentication — browser session vs server-to-server
• Sandbox setup — verify your sandbox is live
• Going live — pre-launch checklist + production cutover
• API Reference — full endpoint catalog