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 Publisher Commerce: in-context checkout, a Buy Now button that encodes the SKU, and publisher/affiliate attribution.
The five phases, Publisher-Commerce framing
| Phase | What happens |
|---|---|
| 1. Hosting | Where checkout renders: the publisher’s site or article surface |
| 2. Authentication | POST /api/v1/browser-session (or use server-to-server auth directly) |
| 3. Discovery | The Buy Now button encodes the SKU via the Embedded Buy Button embed — usually no live discovery/search call |
| 4. Checkout | The shared cart → shipping → payment → complete-order sequence, rendered inline on the article |
| 5. Order placement | Order lands in the merchant’s OMS with publisher attribution |
Sequence diagram
What’s specific to Publisher Commerce
- In-context checkout. Checkout renders inline or in a slide-in panel on the article — the reader never leaves the page. After
complete-order, a compact inline confirmation shows the merchant order ID; the reader closes the panel and keeps reading. - The embed encodes the SKU. The Buy Now button names the product at content-publish time, so add-to-cart can skip discovery.
- Postal-code pre-warm (optimization). Pre-set the postal code from the reader’s geo IP via Set Postal Code so the merchant’s shipping rates are pre-warmed by the time the full address is submitted.
Attribution — article-to-conversion
What defines the Publisher Commerce flow is the article as the surface that drove discovery and the publisher as the traffic source.
| Data | Direction | Why |
|---|---|---|
UTM params (utm_source, utm_campaign, utm_content) |
Page context → cart session → order metadata → merchant OMS | Merchant attribution reports credit the publisher |
| Publisher identifier | Page context → cart session → Firmly attribution → merchant OMS | “Orders from Publisher X” without manual reconciliation |
| Article identifier | Page context → cart session → publisher’s own analytics | Publisher knows which articles drove orders |
| Affiliate commission posting | Order placement → Firmly affiliate service → publisher’s payout system | Publisher gets paid the commission |
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.
Related
- Multi-Product Purchase — multiple items in one in-context cart
- Why Firmly — what makes Publisher Commerce different
- Integration Patterns — embed component vs separate landing options