> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Show the cart and confirm it

> Show the cart from each answer, with its lines, fees, total and the most the card can be held for, then confirm the exact cart the shopper said yes to.

The shopper sees their cart in your app, such as a panel above the chat, with each line, the fees and the total. The panel updates each time the shopper adds an item, changes a quantity or drops the cart. When the shopper says yes, you confirm that exact cart.

## 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.

> [tab] SDK
>
> 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:
>
> ```ts chat.ts theme={null}
> 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, oldest first. To read the carts after the turn ends, use `turn.results`, the whole answer of each call the turn made, in order:
>
> ```ts chat.ts theme={null}
> 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 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.

> [tab] MCP
>
> Every [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) result carries `carts`, one cart for each store, and `grand_totals`, what the carts cost together, one entry for each currency. This result is shortened:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Added 2 Amazon Basics 20-Pack AA Alkaline Batteries from Amazon to your cart, about $20.48 in total. ...",
>   "next_action": "shipping_details",
>   "carts": [
>     {
>       "lines": [ ... ],
>       "total": { "amount_cents": 2048, "currency": "USD" },
>       "total_status": "estimate",
>       "total_is_estimate": true
>     }
>   ],
>   "grand_totals": [ { "amount_cents": 2048, "currency": "USD" } ],
>   "conversation_id": "conv_527d0e58fbd792e797b4d099"
> }
> ```
>
> To read the carts again at any time, call [`get_conversation`](https://docs.agentcard.com/commerce-mcp/tools/get_conversation) with the `conversation_id`. Its carts also carry `cart_hash`, `subtotal` and `fees`. Never show the `conversation_id` to the shopper.

> [tab] API
>
> Every answer to `POST /buy` carries `cart` and `carts`:
>
> ```json theme={null}
> {
>   "conversation_id": "conv_527d0e58fbd792e797b4d099",
>   "status": "needs_input",
>   "reply": "Added 2 Amazon Basics 20-Pack AA Alkaline Batteries from Amazon to your cart, about $20.48 in total. ...",
>   "cart": {
>     "merchant": "retail",
>     "merchant_name": "Amazon",
>     "currency": "usd",
>     "items": [
>       {
>         "name": "Amazon Basics 20-Pack AA Alkaline Batteries, 1.5 Volt, 10-Year Leak-Free Shelf Life, for Everyday and Household Devices",
>         "qty": 2,
>         "priceCents": 999,
>         "lineTotalCents": 1998,
>         "ref": "p_0a02f4ebb745",
>         "url": "https://www.amazon.com/dp/B00NTCH52W",
>         "line_id": "..."
>       }
>     ],
>     "subtotalCents": 1998,
>     "serviceFeesCents": 50,
>     "merchantFeeLines": null,
>     "discounts": [],
>     "pricing": false,
>     "tipCents": 0,
>     "totalCents": 2048,
>     "totalIsEstimate": true,
>     "totalStatus": "estimate",
>     "approvedCeilingCents": 3178,
>     "hold": { "amountCents": 3178, "reason": "checkout_estimate" },
>     "hash": "bde292459dc6b06f"
>   },
>   "carts": [ { ... } ],
>   "next_action": "shipping_details"
> }
> ```
>
> `cart` is the newest cart, or null when there is none. `carts` lists every cart in the conversation, oldest first.

## Show each field

Every amount is a whole number in the smallest unit of the cart's currency, so `2048` 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.

> [tab] SDK
>
> `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:
>
> ```ts money.ts theme={null}
> 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);
> }
> ```

> [tab] MCP
>
> Each cart carries `lines`, `total`, `total_status` and `total_is_estimate`. Money is `{ amount_cents, currency }`. Show the store, the items, their quantities and the total with its currency.
>
> The MCP carts carry no field for the ceiling, the hold, the discounts or a cart that is pricing again, so the next three sections apply to the SDK and the API.

> [tab] API
>
> | 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, optional | The choices made on the line, such as "Extra Guacamole", and the version, such as "Medium". |
> | `subtotalCents` | number or null | The items alone. |
> | `serviceFeesCents` | number or null | Every fee and tax together. |
> | `merchantFeeLines` | array or null | The store's own fee and tax lines inside `serviceFeesCents`, such as `Shipping`. |
> | `discounts` | array | Each discount or coupon inside the total. Empty when there is none. |
> | `tipCents` | number | The tip. |
> | `totalCents` | number | The full total the shopper pays. |
> | `totalIsEstimate` | boolean | True while the store has not priced the tax and shipping yet. |
> | `approvedCeilingCents` | number or null | The most the shopper's bank can set aside on the card for this order. Null when it equals the total. |
> | `hold` | object or null | Why the bank sets aside more than the total. |
> | `pricing` | boolean | True while the store prices this cart again. |
> | `hash` | string | A short code that names exactly this cart at this price. |

### 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. Show `approvedCeilingCents` 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 in `discounts` 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's `ref` 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](https://docs.agentcard.com/opencommerce/guides/showing-products.md) 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 reads `pricing: 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.

> [tab] SDK
>
> The answer has `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:
>
> | `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 or a sign-in to the store. | 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 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`:
>
> ```ts refresh-cart.ts theme={null}
> const conversation = await agentcard.conversation(conversationId, { externalUserId: shopper.id });
> renderCarts(conversation.carts);
> ```
>
> 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_idle` message, and its `facts.nudgeNumber` counts the nudges, 1 for the first and 2 for the second.

> [tab] MCP
>
> A `buy` call answers within about 45 seconds. When `turn_continues` is `true`, Agentcard is still working: tell the shopper you're on it, then read [`get_conversation`](https://docs.agentcard.com/commerce-mcp/tools/get_conversation) or [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates) later. `cart_building` in `get_conversation` is set while a store is still pricing a cart. Never send the same `buy` again.

> [tab] API
>
> The call waits for the store's checkout, so give the request a timeout of a few minutes. The answer then carries the cart at the store's own total:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Le Picardie® Clear Glass Tumbler - Set of 6 (3 oz. / 9cl) at duralexusa.com: $28.36 with tax and shipping, read from the store's own checkout. Confirm to pay with your card.",
>   "cart": {
>     "merchant": "duralexusa.com",
>     "merchant_name": "duralexusa.com",
>     "currency": "usd",
>     "items": [ { "name": "Le Picardie® Clear Glass Tumbler - Set of 6 (3 oz. / 9cl)", "qty": 1, "priceCents": 2000, "lineTotalCents": 2000, ... } ],
>     "totalCents": 2836,
>     "approvedCeilingCents": null,
>     "hold": null,
>     "hash": "8bc4203f8f598903"
>   }
> }
> ```
>
> A confirm sent while the store's checkout still builds the cart is refused:
>
> ```text theme={null}
> 409
> {
>   "error": "The cart at duralexusa.com is still being built, so it has no total yet and nothing was confirmed. ...",
>   "code": "cart_not_ready",
>   "conversation_id": "conv_...",
>   "cart_building": { "store": "duralexusa.com", "started_at": "..." }
> }
> ```
>
> Wait for the answer that carries the cart, show its total, and confirm once the shopper says yes to it.

## 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 whose `next_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](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md) shows.

> [tab] SDK
>
> 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.

> [tab] MCP
>
> Call `buy` once with `confirm: true`:
>
> ```json theme={null}
> {
>   "tool": "buy",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "ask": "yes, place it",
>     "confirm": true,
>     "new_order": false,
>     "product_id": null,
>     "store_id": null
>   }
> }
> ```
>
> A confirm is not safe to repeat. After a timeout or an unclear error, read `get_conversation` first: an approval link in `last_checkout`, or an order in `orders`, means the confirm went through.

> [tab] API
>
> Send the cart's `hash` as `confirm`, with the same `conversation_id`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "conversation_id": "conv_527d0e58fbd792e797b4d099",
>     "external_user_id": "user-42",
>     "confirm": "e4b4091258ac128a"
>   }'
> ```
>
> To confirm carts at several stores at once, send their hashes as an array: `"confirm": ["e4b4091258ac128a", "8bc4203f8f598903"]`.

### Confirm in your own app

Send `place: "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:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_527d0e58fbd792e797b4d099",
    "external_user_id": "user-42",
    "ask": "yes",
    "place": "confirm_only"
  }'
```

A yes the shopper types places nothing. The answer hands back the same cart with `yes_heard: true`, so you can show your own button for it:

```json theme={null}
{
  "status": "needs_input",
  "place": "confirm_only",
  "yes_heard": true,
  "reply": "Nothing is ordered yet. Confirm this cart in the app to place the order.",
  "cart": { "merchant_name": "Amazon", "totalCents": 1024, "hash": "ad9cdf1a1a5037ab", ... }
}
```

When the shopper taps the button, send the cart's `hash` as `confirm`, with `place` still set:

```bash theme={null}
curl https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $AGENTCARD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "conv_527d0e58fbd792e797b4d099",
    "external_user_id": "user-42",
    "confirm": "ad9cdf1a1a5037ab",
    "place": "confirm_only"
  }'
```

Nothing else places an order on such a request: not a yes from an earlier message, not a checkout the agent starts on its own, and not your app's payment permission on its own, which pays only for a cart your app confirmed by its `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:

```text theme={null}
400
{"error":"confirm_hash_required","code":"confirm_hash_required","message":"This request sets place: \"confirm_only\", so only confirm: \"<cart.hash>\" from a previous answer places an order. Nothing ran and nothing was charged. Send the hash of the cart the shopper approved.","place":"confirm_only"}
```

Send the `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.

> [tab] SDK
>
> The tool answers with the cart at the new total, and the model shows it and asks the shopper again.

> [tab] MCP
>
> The result's `carts` holds the new `total`, with `next_action: "confirm"`. Show it, and call `buy` with `confirm: true` again on the shopper's yes.

> [tab] API
>
> The answer carries the cart with a new `hash`:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "The cart total is now different from what I showed you earlier, so I haven't placed the order yet. ... Say yes to place it for $33.36.",
>   "next_action": "confirm",
>   "cart": {
>     "merchantFeeLines": [
>       { "label": "Tax", "amountCents": 258 },
>       { "label": "Shipping", "amountCents": 299 }
>     ],
>     "totalCents": 3336,
>     "totalStatus": "confirmed",
>     "approvedCeilingCents": 3577,
>     "hash": "a03ab61e658c35eb",
>     ...
>   }
> }
> ```
>
> Confirm the new `hash` once the shopper says yes to it.

### 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.

> [tab] SDK
>
> 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.

> [tab] MCP
>
> The call fails with this error:
>
> ```json theme={null}
> { "error": { "code": "cart_changed", "message": "...", "retryable": false } }
> ```
>
> Read the carts with `get_conversation`, show them, and confirm again on the shopper's yes.

> [tab] API
>
> The old hash is refused:
>
> ```text theme={null}
> 409
> {
>   "error": "cart changed since that hash was issued. Verify the current carts and confirm their hashes",
>   "code": "cart_changed",
>   "conversation_id": "conv_527d0e58fbd792e797b4d099",
>   "cart": { "hash": "e4b4091258ac128a", "subtotalCents": 2997, "serviceFeesCents": 75, "totalCents": 3072, ... },
>   "carts": [ ... ]
> }
> ```
>
> The refusal carries the carts as they stand now. Confirm the hash of each cart the shopper still wants. An old hash anywhere in an array refuses the whole array.

### 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.

> [tab] SDK
>
> The tool names the Vault on the confirm for you. There is nothing to add.

> [tab] MCP
>
> `buy` has no payment field to set. There is nothing to add.

> [tab] API
>
> A confirm of such a cart without `payment_source` is refused, and nothing is charged:
>
> ```text theme={null}
> 409
> {
>   "error": "a browser cart is paid with the vault: confirm it with payment_source \"vault\"",
>   "code": "payment_source_vault_required",
>   "conversation_id": "conv_8dfb71d043e3eeb1e70c4caa"
> }
> ```
>
> Send the same confirm again with `"payment_source": "vault"`.

## 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.

1. Send "two packs of AA batteries from amazon" as a test shopper, and pick a product.
2. Check that your panel shows the line, the fees and the total, and that the numbers match the answer's cart.
3. Send "make it three". Check that the panel updates.
4. Ask for an item at a second store. Check that the panel shows two carts.
5. Answer the address questions, then confirm. When the answer carries a new total, confirm again.
6. Check that the confirm ends with status `declined` and decline code `sandbox_mode`. A test card cannot pay a real store, so this is the expected end of a sandbox purchase.
7. Send "start over". Check that the panel clears.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.