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

Multi-Product Purchase

​​ Scope

A multi-product Ad Commerce cart holds items from a single merchant — a bundle ad creative (multiple SKUs in one click), or a post-click landing with related-product upsells.

The cart-mutation, shipping, and order-completion mechanics are the shared Firmly cart flow — because the cart is built across those calls, checkout finalizes with complete-order, not the one-shot place-order. See Agentic Commerce → Multi-Product Purchase for the cart-modification table, multi-shipment handling, and the race-condition retry pattern. This page covers the Ad-specific entry and cart-review surfaces.

​​ What’s different from single-product

  1. Multi-item entry — the ad creative lists multiple bundled SKUs at click time, or the post-click landing offers related products as upsells.
  2. Cart Review — a compact cart panel or modal in the ad surface, or a full cart page on the landing.

​​ Multi-item entry in code

For a bundle ad where the creative names multiple SKUs, add them sequentially:


// callFirmly: fetch wrapper adding x-firmly-authorization; see the Quickstart

// DOMAIN: the merchant domain (e.g., staging.luma.gift)

// Endpoint paths below are relative to /api/v2/domains/{domain}

// Bundle SKUs from the ad creative metadata

const bundle = [
  { add_to_cart_ref: { variant_id: 'hoodie-black-m' }, quantity: 1 },
  { add_to_cart_ref: { variant_id: 'beanie-wool' },    quantity: 1 }

];



let cart;

for (const item of bundle) {
  cart = await callFirmly(`/api/v2/domains/${DOMAIN}/cart/line-items`, item);

}



// Cart now has all items; render the cart panel in the ad surface

renderCartPanel(cart);

For a related-product upsell on a post-click landing, each Add is a separate POST /cart/line-items, with the cart panel updating after each.

​​ Cart Review surfaces

​​ Mode A — Compact cart panel (in-ad checkout)

If the ad surface supports in-ad checkout (no redirect), the cart panel is a compact overlay inside the creative — quantity controls, remove buttons, and a Checkout CTA.

​​ Mode B — Post-click landing cart page

For ad-click-to-landing flows, the cart is a full page on the landing surface with the standard cart UX (line items, totals, promo input, checkout button).

​​ Express checkout

Ad surfaces lean on express checkout to cut drop-off — Google Pay (one tap on mobile), PayPal Express, or Klarna BNPL, each spanning the full cart rather than per-item.

​​ Attribution

Click-ID, UTM, and order metadata flow identically to Single Product — the merchant sees one order with multiple line items, all tagged with the same ad-platform attribution.