Read the cart from each answer
Every answer carries the carts as they stand after that call. Read them from the answer’s fields, not from the reply text. A shopper buying at two stores has one cart at each, and each cart is its own order that the shopper confirms on its own. Show every cart, so the shopper hears about each one.- SDK
- MCP
- API
Pass An
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:chat.ts
result.cart is the newest cart, and result.carts lists every cart, oldest first. To read the carts after the turn ends, use turn.results, the whole answer of each call the turn made, in order:chat.ts
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 card 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.Show each field
Every amount is a whole number in the smallest unit of the cart’s currency, so2048 in USD is $20.48 and 1331 in JPY is ¥1,331. Show each amount in its own currency, and never add amounts in different currencies.
- SDK
- MCP
- API
result.cart and each entry in result.carts hold the fields the API tab lists, with the same names. Each line also carries url, the product’s page. A short formatter turns any amount into text:money.ts
Show an estimate as an estimate
When the cart says its total is an estimate (totalIsEstimate in the SDK and the API, total_is_estimate in MCP), the total covers the items and the fees Agentcard knows, before the store adds tax and shipping. Show it as an estimate, such as “about $20.48 before tax and shipping”. DoorDash prices a cart once the shopper’s own account holds it, so its first total is an estimate. Once the store prices the cart, the total status reads confirmed, and in the SDK and the API merchantFeeLines lists the store’s own lines.
Show the card’s hold
A store that adds tax and shipping only as it places the order asks the shopper to approve more than the estimate. ShowapprovedCeilingCents beside the total whenever it is not null, such as “up to $31.78”. A shopper who sees only the total approves less than the card can be held for. The shopper’s bank sets that amount aside on the card until the order goes through, and releases what the store does not use.
Read hold.reason to word the line. checkout_estimate is that room for tax and shipping, so show it beside the total. flight and hotel mean a booking set that amount aside, and the shopper sees it on their statement, so show a line such as “Card held for $353.01”.
Show discounts as money off
Each entry indiscounts has a label, a negative amountCents and a kind. Show it as money off, such as “DashPass discount −$3.00”. The total already includes it, so never take it off a second time. The same line also appears in merchantFeeLines, so leave the negative fee lines out of a panel that shows discounts on their own. A coupon carries the code the store accepted in code, and a discount has none.
Show what is already in the cart
A cart line’sref is the ref of the product card it came from. A product whose ref matches is in the cart, so its card can show an In cart badge. In the API, card_refs on a line lists every card that stands for it. Show products and add the pick covers the cards.
Wait for a store’s own checkout
At some stores, Agentcard fills in the store’s own checkout page to build the cart and read the store’s total. That takes about 30 seconds, sometimes longer. Show the shopper that the total is on its way, and offer no confirm until the cart arrives with its total. A cart already on the screen whose store prices it again readspricing: true in the SDK and the API, and several carts can read it at once. Show “Pricing” in place of that cart’s total until an answer brings it back as false.
A confirm sent while the store’s checkout still builds the cart confirms nothing and charges nothing.
- SDK
- MCP
- API
The answer has A shopper message sent while the cart builds waits for the cart, and the shopper reads a line saying the store is still building it. A cart that sat without being sent for approval produces a
cart_building set, with the store’s name and when it started, and carries no cart yet. A confirm in that state answers needs_input with error_code: cart_not_ready.Agentcard sends the cart in a purchase.message when the store’s checkout finishes. Post its text as it is:The message carries text and facts, not the cart. When
cart_ready or cart_failed arrives, read the conversation the answer that started the cart named, and show its carts:refresh-cart.ts
cart_idle message, and its facts.nudgeNumber counts the nudges, 1 for the first and 2 for the second.Confirm the shopper’s cart
Confirm only on the shopper’s clear yes to the cart you showed, or when they ask to check out. “Looks good” is interest, not a yes. Before you confirm, check the cart against what the shopper read: the same store, the same lines and quantities, and the same total. An answer whosenext_action is confirm waits only for the shopper’s yes. A confirm sent before the order has what it needs, such as a shipping address, pays nothing and answers with that question. After the confirm, the shopper approves the payment on a page Agentcard hosts, as Approving a purchase shows.
- SDK
- MCP
- API
The model sets
confirm to true when the shopper says yes. The tool then confirms the cart Agentcard last showed by its hash, a short code that names this exact cart at this price, so your code handles no hash and no conversation id.Confirm in your own app
Sendplace: "confirm_only" when your app takes the shopper’s yes on its own screen, such as a Pay button. On that request, only your confirm of the cart’s hash places an order. Send it on every request about the purchase:
yes_heard: true, so you can show your own button for it:
hash as confirm, with place still set:
hash. Agentcard refuses confirm: true before anything runs, and it also refuses a confirm your app sends with carried, the field for a yes carried over past the shopper’s store sign-in or card step:
hash of the cart the shopper confirmed in your app.
Every answer to such a request carries place: "confirm_only". If an answer lacks it, Agentcard did not apply your setting, so stop and check the request before you show the shopper anything.
The Commerce SDK’s client sends place from buy() and reads place and yes_heard on each answer. The buy tool your model calls does not take place yet.
Handle a new total
When the store prices the cart as you confirm, its total can move from the estimate. Agentcard then pays nothing and answers with the cart at the store’s total. Show the new total, and confirm again once the shopper says yes to it.- SDK
- MCP
- API
The tool answers with the cart at the new total, and the model shows it and asks the shopper again.
Handle a cart that changed
When the cart changed after the shopper saw it, such as a new quantity, the confirm is refused and nothing is charged. Show the cart as it stands now, and ask the shopper again.- SDK
- MCP
- API
The tool answers
needs_input with error_code: cart_changed and the cart as it stands now. The model shows the shopper the new total and asks again.Pay at a store’s own checkout
A cart Agentcard built on the store’s own checkout page is paid with the card the shopper saved in the Vault, Agentcard’s page where the shopper saves their card and approves a payment.- SDK
- MCP
- API
The tool names the Vault on the confirm for you. There is nothing to add.
Check it in the sandbox
The sandbox, Agentcard’s test mode, runs every step up to payment against real stores and charges nothing. Sandbox credentials run every call there.- Send “two packs of AA batteries from amazon” as a test shopper, and pick a product.
- Check that your panel shows the line, the fees and the total, and that the numbers match the answer’s cart.
- Send “make it three”. Check that the panel updates.
- Ask for an item at a second store. Check that the panel shows two carts.
- Answer the address questions, then confirm. When the answer carries a new total, confirm again.
- Check that the confirm ends with status
declinedand decline codesandbox_mode. A test card cannot pay a real store, so this is the expected end of a sandbox purchase. - Send “start over”. Check that the panel clears.