Showing the cart

The shopper sees their cart in your app, such as a panel above the chat input, with each line, the fees, and the total. The cart updates every time the shopper adds an item, changes a quantity, or drops the cart. The shopper reads the numbers from your panel, and the model’s reply only moves the conversation along.

Read the cart from each answer

Pass onResult to buy.turn. It gets the whole answer once for each call, after the call’s links went out and before the model reads it. You wrap no tool and parse no JSON.

chat.ts

const turn = buyFor(shopper.id).turn(message, {
  onResult: (result) => showCartPanel(shopper.id, result.carts, result.next_action), // your code
});

result.cart is the newest cart, and result.carts lists every cart on the table, oldest first. A shopper buying from more than one store has one cart for each store, and each cart is its own order that the shopper confirms on its own. Show every cart in carts, so the shopper hears about each one. To read the carts after the turn ends, use turn.results. It holds the whole answer of each call the turn made, in order:

chat.ts

const carts = turn.results.at(-1)?.carts ?? [];

An onResult passed to buyTool hears every call the tool makes. Pass it to buy.turn to hear only the answers of one message, so one message’s cart never lands beside another message’s reply. A refusal the tool turns into an answer, such as the Vault link for a shopper with no card, reaches onResult too. A call that throws calls nothing, and an onResult that throws costs only that call to it.

Render each field

Every amount is in the minor unit of the cart’s currency, the store’s ISO 4217 code, so 1331 is \$13.31 in USD and ¥1,331 in JPY.

Field	Type	What to show
`merchant_name`	string	The store the cart is at.
`items[].name`, `items[].qty`	string, number	The line’s name and quantity.
`items[].lineTotalCents`	number or null	What the line costs with its add-ons and quantity. The lines add up to `subtotalCents`.
`items[].priceCents`	number, optional	One unit’s price.
`items[].options`, `items[].variant`	string[], string or null	The choices made on the line, such as “Chicken” and “Extra Guacamole”, and the variant, such as “Birthday (Medium)”.
`items[].url`, `items[].ref`	string or null	The product’s page, and the id of the product card the line is.
`subtotalCents`	number or null	The items alone.
`serviceFeesCents`, `merchantFeeLines`	number, array or null	The fees, and the store’s own fee and tax lines inside them, such as `Delivery Fee`.
`tipCents`	number	The tip.
`totalCents`	number	The all-in total the shopper sees.
`totalIsEstimate`	boolean	True when the store has not priced the fees and tax yet.
`approvedCeilingCents`	number or null	The most the card can be held for, or null when it equals the total.
`hash`	string	Identifies exactly this cart at this price.

A short formatter turns minor units into text for any currency:

money.ts

export function money(cents: number, currency: string | null): string {
  const code = currency ?? 'USD';
  const format = new Intl.NumberFormat('en-US', { style: 'currency', currency: code });
  return format.format(cents / 10 ** format.resolvedOptions().maximumFractionDigits);
}

Show an estimate as an estimate

When totalIsEstimate is true, the total covers the items and the known fees only. Show it as an estimate, such as “about $18.41 before tax and delivery”. DoorDash prices a cart once the shopper’s own account holds it, so its first total is an estimate.

Show the ceiling beside the total

A store that adds shipping and tax only as it places the order asks the shopper to approve more than the total. Show approvedCeilingCents whenever the cart carries one. A shopper who sees only the total approves less than the card can be held for.

Mark the products that are in the cart

A line’s ref is the id of the product card it is. A product in result.products whose ref matches is in the cart, so your product cards can show an In cart badge.

Show a cart the store is still building

Some stores build the cart in their own checkout, which takes about 30 seconds. The answer then has cart_building set, with the store’s name and when it started, and carries no cart yet. Show the shopper that the total is on its way, and do not offer a confirm. Agentcard sends the cart in a purchase.message when the store’s checkout finishes. Post text as it is.

`kind`	What happened	What to do
`cart_ready`	The store’s checkout built the cart and read its own total. Nothing is paid until the shopper says yes to it.	Show the cart, and let the shopper say yes.
`cart_needs_input`	The checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store, or an approval of the most the order can cost.	The shopper’s reply continues the cart, so post the question as it is.
`cart_failed`	The checkout built no cart, and nothing was ordered or charged.	Let the shopper ask again, or ask for another product.

The model’s description tells it to confirm a cart that is still building only after the shopper says yes to the total in the message Agentcard sends next. A shopper message sent while the cart builds waits for the cart, and the shopper reads a line saying the store is still building the cart. A cart that sat without being sent for approval produces a cart_idle message. Its facts.nudgeNumber counts the nudges, 1 for the first and 2 for the second.

Check it in the sandbox

Send “two packs of AA batteries from Amazon” as a test shopper, and tap a product card.
Check that your panel shows the line with its name, quantity, and price, the fees, and the total, and that the numbers match result.cart.
Send “make it two”. Check that the panel updates and the cart’s hash changes.
Ask for an item at a second store. Check that the panel shows two carts.
Send “start over”. Check that the panel clears.

Getting started

Guides

Vault

Issuing

Commerce SDK

Partners

Read the cart from each answer

Render each field

Show an estimate as an estimate

Show the ceiling beside the total

Mark the products that are in the cart

Show a cart the store is still building

Check it in the sandbox

​Read the cart from each answer

​Render each field

​Show an estimate as an estimate

​Show the ceiling beside the total

​Mark the products that are in the cart

​Show a cart the store is still building

​Check it in the sandbox

Read the cart from each answer

Render each field

Show an estimate as an estimate

Show the ceiling beside the total

Mark the products that are in the cart

Show a cart the store is still building

Check it in the sandbox