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. This page covers only what’s specific to Ad Commerce: click-ID capture, an ad creative that names the SKU, and the conversion postback.

​​ The five phases, Ad-Commerce framing

Phase What happens
1. Hosting Ad creative or post-click landing surface
2. Authentication POST /api/v1/browser-session (or use server-to-server auth directly)
3. Discovery The ad creative encodes the SKU (via the click_through URL) — usually no live discovery/search call
4. Checkout The shared cart → shipping → payment → complete-order sequence
5. Order placement Order lands in the merchant’s OMS with click-ID; a conversion postback fires to the ad platform

​​ Sequence diagram

​​ What’s specific to Ad Commerce

  • Click-ID capture. On ad click, capture the platform’s click-ID (fbclid for Meta, gclid for Google, ttclid for TikTok, epik for Pinterest) and persist it for the session — before any API call.
  • The ad encodes the SKU. The creative’s click_through URL carries the product handle or variant ID, so add-to-cart can skip discovery.
  • Wallet-first payment. Mobile ad surfaces lean on Google Pay to cut drop-off; card via JWE is the fallback.
  • Conversion postback. After cart_status === "submitted", fire the ad platform’s conversion event with the click-ID (Meta CAPI, Google Ads, TikTok Events, Pinterest CAPI). Wire it after success, never before. On a 5xx or network error, retry with backoff; on a 4xx, log and alert (the payload is malformed and a retry will fail again) — either way, don’t surface it to the viewer, who has already paid.

​​ Attribution — closing the ad loop

What defines the Ad Commerce flow is proper attribution back to the ad platform. Three data flows matter:

Data Direction Why
Click-ID (fbclid, gclid, etc.) Ad click → session → order metadata Ad platform credits the conversion
UTM params Ad click → session → merchant OMS Merchant’s own attribution reports
Conversion postback Order placement → ad platform Optimization model gets the signal to find more conversions

Bind the click-ID and UTM params to the cart with Set Cart Attribution (PUT .../cart/attribution), called after add-to-cart and before checkout. It takes four optional string fields — utm, referrer_url, referral_code, and landing_page — which flow through to the merchant’s order metadata. Fold the click-ID into the utm query string (e.g. utm_source=meta&fbclid=...), and use referrer_url / landing_page for the ad and post-click URLs. The conversion postback is your call to fire after order success — Set Cart Attribution feeds the order metadata; it does not fire the postback.

Without the postback, the campaign won’t learn — every order should fire one.

​​ 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, or the Advanced Checkout Guide for a runnable script.