Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. For Destinations

For Destinations

If you’re a destination — an AI agent, publisher, ad platform, marketplace operator, or brand partner — Firmly is the commerce backend that powers discovery, cart, and checkout across merchants — all through a single integration.

One App ID, one API collection, and your surface can transact against every Firmly-connected merchant.

The merchant stays the merchant of record. They are the seller, their payment processor charges the buyer, and their systems own fulfillment. For you that means no payment licensing or PCI scope, no sales-tax registration, no chargeback queue, no returns desk, and no inventory risk — so adding the tenth merchant costs you no more regulatory work than the first. See Is Firmly the merchant of record? for the full breakdown.

​​ How it works

How Firmly works for a destination — your surface calls Firmly’s APIs (discovery, cart, checkout, payment, order, attribution); Firmly places the order with the merchant; order confirmation and affiliate attribution flow back to your surface

​​ Choose your checkout flow

Start with Standard — it fits most integrations. Move up to Advanced when you need split shipments, delivery scheduling, add-ons, or ZIP coverage. Auth, catalog, and discovery are the same for both — only the cart, checkout, and order calls differ, so switching later is cheap.

Most integrations
Standard

Simple checkout for a single, known merchant.

  • Browse, cart, pay, place order
  • One-shot "buy now"
  • Promo codes, addresses, consents
  • Single-shipment delivery
Runs on /api/v1
Standard Checkout Guide →
Rich retail
Advanced

Everything in Standard, plus richer fulfillment.

  • Split shipments across items
  • Delivery scheduling and pickup
  • Add-ons and protection plans
  • Coverage by ZIP before checkout
Runs on /api/v2 · needs merchant support
Advanced Checkout Guide →

​​ How destinations onboard

Destinations onboard through a Firmly-issued App ID plus a paired test merchant. Firmly provisions each App ID directly, so your test merchant, environment scope, and per-destination configuration are already correct when you make your first call.

The flow is: request a sandbox App ID from Firmly (typically within one business day) → receive your App ID + a test merchant → make your first API call. Sandbox is where you build; production is a separate App ID issued after the integration is verified.

Destinations write code. Merchants don’t — they sign up on Firmly Connect and walk through a wizard. The two sides are kept clean: destinations build against APIs, merchants configure through forms.

For the API reference, see API Reference. For solution-specific patterns (Agentic Commerce, Publisher Commerce, Ad Commerce, Marketplace, Branded Commerce), see Solutions.

Once Firmly provisions your App ID, it invites your team to the Destination Dashboard — the surface you sign into to track your funnel, review orders, manage your team, and read audit logs. See Destination Dashboard for the full reference.

​​ The 6-step destination journey

# Step Who does it What it is
1 Request an App ID You Email or contact Firmly with your destination type and intended integration shape
2 Receive App ID + test merchant pairing Firmly Sandbox App ID and a test merchant domain provisioned for you
3 Sandbox setup You Verify auth, search, and the test merchant catalog with a few curl calls
4 Build your integration You Implement against the API reference — discovery, cart, checkout, payment
5 Pre-launch review Firmly + You Walk through your integration, error handling, rate-limit posture, and observability
6 Production App ID Firmly Production App ID issued; production merchants enabled

The App ID issuance step (step 2) is manual — there’s no auto-provisioning. Most destinations receive their sandbox App ID within one business day of the initial request.

​​ What you get

One API, all merchants Discovery, cart, checkout, payment, tax, shipping, and order placement — the same API surface against every merchant on Firmly’s network.
Real merchant catalogs Live pricing, real-time inventory, and authentic merchant order flows — your users transact against the real store, not a simulation.
No per-merchant integration You integrate Firmly once. Adding a new merchant on Firmly’s side doesn’t require any change on yours.
Sandbox parity Sandbox uses the same API shapes, flow, and base URLs as production — the only differences are your App ID and the test merchant.
Payment flexibility Card via JWE encryption, Google Pay, PayPal, Klarna, Click to Pay, and Agentic Pay for autonomous agents — pick what fits your surface.
Affiliate attribution Orders are tagged with your destination identifier so commissions and attribution flow correctly without manual reconciliation.
Try the Sandbox Request a sandbox App ID, then call the API against a test merchant Find your solution Agentic, ad, branded, marketplace, publisher — pick the integration shape that fits before you build Standard Checkout Guide The simplest path — the Standard (v1) flow end-to-end in ~90 lines of Node. Right for most integrations Advanced Checkout Guide The richer Advanced (v2) flow — split shipments and add-ons — end-to-end in ~150 lines of Node Onboarding The App ID handshake — what Firmly issues, what you provide Authentication Browser session vs server-to-server — pick the right auth model Sandbox setup Verify your sandbox is live with three curl calls Going live Pre-launch checklist and the production App ID handover

​​ What stays on your side, what’s on Firmly’s

Layer Where it lives
Your user-facing surface (chat, search, ad placement, publisher page, marketplace UI) Yours — Firmly doesn’t render anything in your UI
The shopping experience (discovery, cart, checkout) Yours — your code calls Firmly’s APIs and renders the results in your surface
Merchant catalogs, inventory, pricing Firmly — read from each merchant’s commerce backend by Firmly’s platform adapter
Payment processing Firmly — card encryption, network token, alternative payment methods
Order placement at the merchant Firmly — orders land in the merchant’s existing order management system
Attribution and reconciliation Firmly — your destination identifier is tagged on every order

​​ What about merchants

Merchants don’t need to do anything special for your destination to start transacting — they opt into Firmly’s network through Firmly Connect, and once they’re live, every destination on the network can sell their catalog (subject to per-destination opt-ins).

When Firmly issues your sandbox App ID, it’s paired with a specific test merchant. In production, your App ID is scoped to the merchants your destination is approved to transact against.