Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. Solutions
  3. ...
  4. Flows
  5. Single Product Purchase

Single Product Purchase

The underlying API sequence is the shared Firmly cart flow — identical to Agentic Commerce → Single Product Purchase, which has the full curl-by-curl walkthrough and the cart-response field reference. This page covers only what’s specific to Marketplace: the operator-owned surface, discovery across merchants, and operator attribution.

​​ The five phases, Marketplace framing

Phase What happens
1. Hosting The marketplace operator’s own UI — their domain, their brand
2. Authentication POST /api/v1/browser-session (or use server-to-server auth directly)
3. Discovery The operator’s search calls POST /api/v1/discovery/search; results span the operator’s merchant set, each with a domain identifying its source merchant
4. Checkout The shared cart → shipping → payment → complete-order sequence, rendered in the operator’s UI
5. Order placement Order lands in the source merchant’s OMS with marketplace-operator attribution

​​ Sequence diagram

​​ What’s specific to Marketplace

  • Discovery spans merchants. discovery/search returns products across every merchant the operator’s App ID can reach; each product carries a domain field, and the operator’s UI typically shows merchant identity alongside the listing.
  • The cart is scoped to the listing’s source merchant — the {domain} in the cart endpoint URL comes from the product the buyer picked.
  • Operator-branded confirmation. The operator’s confirmation page shows the merchant’s native order identifier under the marketplace’s brand, and links to the merchant’s order status for post-order detail. Anything post-order — tracking, returns, refunds — lives with the source merchant.

​​ Attribution

What defines the Marketplace flow is the marketplace operator as the traffic source while the source merchant retains the seller-of-record relationship with the buyer.

Data Direction Why
Marketplace operator ID Operator UI session → order metadata → merchant OMS Lets the merchant see “orders from Operator X”
Per-listing source merchant Discovery response → cart {domain} Each product carries its source merchant
Order completion event Complete-order response → operator’s own reporting Operator’s marketplace analytics

​​ What can go wrong

Because a marketplace surface aggregates many merchants, the most common failures show up at discovery:

Step Failure What it means for the operator
Discover StoreUnavailable / DomainNotFound A listing points at a merchant that isn’t enabled for the operator’s surface, or the domain is wrong — hide or refresh the listing
Discover 404 ucp_disabled (UCP layer only) The merchant isn’t enabled for agentic/UCP traffic on this surface — remove it from marketplace search until enabled
Add to cart ProductNotFound, NotEnoughStockError (409) The listing is stale — re-fetch the product or mark it out of stock
Place order CreditCardDeclined (422) Payment failed — let the buyer retry with another method

See Errors & Conventions for the full catalog and exact error names, or the For Destinations troubleshooting table.

​​ The shared cart sequence

The add-to-cart, shipping, and order-completion calls are identical across solutions, including the usual checkout tail (set shipping method → get/set consents → billing → payment key → complete order). Because the cart is built across those calls, the tail finalizes with complete-order (existing cart), not the one-shot place-order. Follow Agentic Commerce → Single Product Purchase for the step-by-step and the cart-response field reference, or the Advanced Checkout Guide for a runnable script.