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

# Bring back a saved cart

> Show a returning shopper the cart they left, price every store again, and let them buy it with one yes.

A shopper who leaves a cart and comes back finds it waiting. Your app shows what they put in the cart at each store at once. Agentcard then reads every store's price again, and the shopper sees which prices held, which changed and what sold out before they approve anything. Nothing is charged until the shopper says yes to the prices they read today.

Agentcard saves a cart for every purchase your shoppers start, one cart per conversation, with a line for each store. A conversation is one purchase. You call nothing to save the cart.

## List the shopper's carts

Read the shopper's carts when they come back. The newest comes first, and a page holds up to 20.

Each cart holds its lines, one per store. A line carries the store's name, the items, the quantities, the choices the shopper made such as a size, and the total that store last read. Show the cart from these fields at once, before any store is read again, so the shopper never waits on an empty screen. Each cart also carries a `version`, a number that goes up each time the cart changes, which you send back when you change the cart.

Pass your own id for a chat to read only that chat's carts.

> [tab] SDK
>
> ```ts carts.ts theme={null}
> const { carts, nextCursor } = await agentcard.listCarts({ externalUserId: shopper.id });
> ```
>
> Pass `threadId` to read one chat's carts alone, and pass `nextCursor` as `cursor` for the next page. Read one cart by its id with `getCart(cartId, who)`.

> [tab] MCP
>
> Call [`list_carts`](https://docs.agentcard.com/commerce-mcp/tools/list_carts):
>
> ```json theme={null}
> {
>   "tool": "list_carts",
>   "arguments": { "shopper_id": "user-42", "thread_id": "dm-user-42" }
> }
> ```
>
> ```json theme={null}
> {
>   "carts": [
>     {
>       "cart_id": "cart_410e3cdfb197971262a3afd3",
>       "conversation_id": "conv_4b7fd64f81e303297a40d99c",
>       "state": "changed",
>       "version": 1,
>       "total": { "amount_cents": 999, "currency": "USD" },
>       "expires_at": "2026-11-26T21:02:25.820Z",
>       "lines": [{ "line_key": "amazon", "seller": "Amazon", "state": "saved", "total": { "amount_cents": 999, "currency": "USD" }, "items": [ ... ] }]
>     }
>   ],
>   "next_cursor": null
> }
> ```
>
> Pass `next_cursor` as `cursor` for the next page. Read one cart by its id with [`get_cart`](https://docs.agentcard.com/commerce-mcp/tools/get_cart). A company whose saved carts are not turned on yet gets the error `carts_not_available`.

> [tab] API
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/carts?external_user_id=user-42" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "carts": [
>     {
>       "id": "cart_410e3cdfb197971262a3afd3",
>       "conversation_id": "conv_4b7fd64f81e303297a40d99c",
>       "thread_id": null,
>       "label": "Amazon",
>       "state": "changed",
>       "version": 1,
>       "total_cents": 999,
>       "currency": "USD",
>       "priced_at": "2026-11-19T21:02:25.820Z",
>       "expires_at": "2026-11-26T21:02:25.820Z",
>       "lines": [
>         {
>           "key": "amazon",
>           "seller": "Amazon",
>           "state": "saved",
>           "total_cents": 999,
>           "items": [{ "title": "Amazon Basics 20-Pack AA Alkaline Batteries", "quantity": 1, "unit_price_cents": 999, "options": [] }]
>         }
>       ]
>     }
>   ],
>   "next_cursor": null
> }
> ```
>
> `label` is a short name for the cart made from its stores, such as `Rocket Dog + Amazon`. Add `thread_id` to the query to read one chat's carts, and `cursor` set to `next_cursor` for the next page. Read one cart with `GET /buy/carts/cart_410e3cdfb197971262a3afd3?external_user_id=user-42`.

## Price every store again

Ask Agentcard to read every store's total again when the shopper opens the cart. This step is called a resume, since it brings the cart back. The answer holds the cart as it stands now and one change per store, with the total the shopper last saw and the total the store reads now.

| Outcome | What happened | What to show |
| - | - | - |
| `ready` | The store reads the same total. | The total, and a yes to buy. |
| `changed` | The total moved, or the store gave an estimate. | Both totals, then a yes to buy at the new one. |
| `checking` | The store is still pricing. | "Still pricing" until its new total arrives. |
| `needs_input` | The store asks the shopper something first. | The store's question from `ask`. |
| `unavailable` | The store no longer sells it. | That it sold out or is gone. |
| `failed` | Agentcard could not read that store just now. | That the price could not be read. The line stays saved. |

A change's reason says more about some of them:

| Reason | What it means |
| - | - |
| `address_needed` | The store needs a delivery address before it can price the cart. Send the address as the shopper's next message, as [Send the yes to the cart](#send-the-yes-to-the-cart) shows, and resume again. |
| `fees_pending` | The store has not added its fees yet, so the new total is the items alone. Get the total with fees before the shopper pays. |
| `listed_price` | The price the store lists, before tax and shipping, for a store your own agent checks out. See [Hand a store to your agent](#hand-a-store-to-your-agent). |
| `sold_out` | The item or the size sold out. |
| `offer_expired` | A fare, a room or a time slot is no longer offered. When the seller still has close choices, the change reads `needs_input` and `ask.options` lists up to three. When it has none, the change reads `unavailable`. |
| `offer_gone` | The store no longer lists the product. |
| `replace_account_cart` | The shopper's own cart at the store holds another order. See below. |
| `currency_changed` | The store now prices in another currency, so the old total no longer applies. |

A resume can take up to 90 seconds when a store's own checkout runs again. A store still pricing when the resume answers reads `checking`, and its total arrives later, as [Hear a late price](#hear-a-late-price) shows.

When the shopper's own DoorDash cart already holds another meal, the change reads `needs_input` with `replace_account_cart`. Its `holds` field names what that DoorDash cart holds now, with a token that names exactly that cart. Ask the shopper whether to replace it, and on their yes resume again with the line and that token. A DoorDash cart that changed since the question is asked about again, never cleared.

> [tab] SDK
>
> ```ts resume.ts theme={null}
> const resumed = await agentcard.resumeCart(cart.id, { externalUserId: shopper.id });
> for (const change of resumed.changes) showChange(change); // your code
> ```
>
> `resumed.cart` is the cart now, and each change in `resumed.changes` carries `outcome`, `reason`, `beforeCents` and `nowCents`. To replace the shopper's DoorDash cart on their yes:
>
> ```ts resume.ts theme={null}
> await agentcard.resumeCart(cart.id, { externalUserId: shopper.id }, {
>   replace: [{ key: change.key, holds: change.holds.token }],
> });
> ```

> [tab] MCP
>
> Call [`resume_cart`](https://docs.agentcard.com/commerce-mcp/tools/resume_cart):
>
> ```json theme={null}
> {
>   "tool": "resume_cart",
>   "arguments": { "shopper_id": "user-42", "cart_id": "cart_410e3cdfb197971262a3afd3" }
> }
> ```
>
> ```json theme={null}
> {
>   "cart": { "cart_id": "cart_410e3cdfb197971262a3afd3", "state": "ready", "version": 9, "total": { "amount_cents": 1085, "currency": "USD" }, "lines": [ ... ] },
>   "changes": [
>     { "line_key": "amazon", "outcome": "ready", "before": { "amount_cents": 1085, "currency": "USD" }, "now": { "amount_cents": 1085, "currency": "USD" } }
>   ]
> }
> ```
>
> `before` is the total the shopper last saw, and `now` is the total the store reads now. After a timeout, read `get_cart` before you call again. To replace the shopper's DoorDash cart on their yes, call again with `"replace": [{ "line_key": "doordash", "holds": "<holds.token from the change>" }]`.

> [tab] API
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/resume \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42" }'
> ```
>
> ```json theme={null}
> {
>   "cart": { "id": "cart_410e3cdfb197971262a3afd3", "state": "ready", "version": 9, "total_cents": 1085, "lines": [ ... ] },
>   "changes": [
>     { "key": "amazon", "route": "retail", "outcome": "ready", "before_cents": 1085, "now_cents": 1085 }
>   ]
> }
> ```
>
> Give your HTTP client a timeout above 90 seconds. A store that needs an address answers like this:
>
> ```json theme={null}
> {
>   "changes": [
>     { "key": "amazon", "route": "retail", "outcome": "needs_input", "before_cents": 999, "now_cents": null, "reason": "address_needed", "ask": { "message": null, "fields": ["address"] } }
>   ]
> }
> ```
>
> To replace the shopper's DoorDash cart on their yes:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/resume \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42", "replace": [{ "key": "doordash", "holds": "..." }] }'
> ```

## Hear a late price

A store that answers after the resume sends its total on its own: `cart.line_checking` while it prices, then `cart.line_ready`, `cart.line_changed`, `cart.line_unavailable` or `cart.line_needs_input`. `cart.ready` follows once every store has given its own total. Change that store's line in your chat when its total lands.

> [tab] SDK
>
> Read each event with `cartEventOf`, from `agentcard.listen` or your webhook handler, and match it to the cart and the store's line.

> [tab] MCP
>
> The MCP server sends no event for a late price. Call [`get_cart`](https://docs.agentcard.com/commerce-mcp/tools/get_cart) again a little later, and read the store's line for its new `state` and `total`.

> [tab] API
>
> Agentcard posts each event to your company's [webhook endpoint](https://docs.agentcard.com/webhooks/overview.md), the address on your server that Agentcard sends a request to when something happens. A server with no public address can ask for the events instead. A call with no `after` starts at the present moment and answers a `cursor`. Send that `cursor` as `after` on the next call:
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/api/v2/events?types=cart.*&after=1795122207380_" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "object": "list",
>   "data": [
>     {
>       "cursor": "1795122214175_",
>       "event": {
>         "id": "evt_e6f074c5c60cd7883914cf0a",
>         "type": "cart.line_ready",
>         "livemode": false,
>         "data": { "cart_id": "cart_410e3cdfb197971262a3afd3", "version": 9, "cart_state": "ready", "line_key": "amazon", "seller": "Amazon", "state": "ready", "total_cents": 1085, "currency": "USD", "external_user_id": "user-42", ... }
>       }
>     }
>   ],
>   "cursor": "1795122214175_",
>   "has_more": false
> }
> ```
>
> Keep sending each answer's `cursor` as `after`, so no event between two calls is missed. Match the event to the cart by `cart_id` and to the store by `line_key`. `livemode: false` marks an event from the sandbox, Agentcard's test mode, which charges nothing.

## Text it in a chat

In a chat that shows text alone, such as SMS or iMessage, send the shopper two messages: what they saved, at once, and what each store reads today, once the resume answers.

```text theme={null}
Here's the cart you saved:
• rocketdog.com: Miette Sneaker, $63.98
• Amazon: USB-C cable, $16.34
Checking today's prices now.
```

```text theme={null}
Today's prices:
• rocketdog.com: now $67.98, was $63.98
• Amazon: still pricing
Reply yes to buy the rest now, or wait and I'll tell you here when Amazon is priced.
```

When a store still pricing sends its total, text the shopper that store's new total.

> [tab] SDK
>
> `resumeCartAsText` writes and sends both messages:
>
> ```ts sms.ts theme={null}
> const resumed = await agentcard.resumeCartAsText(cart.id, { externalUserId: shopper.id }, (text) => sendSms(shopper, text)); // your code
> ```
>
> When a store still pricing settles, `savedCartSettled` writes its text. Pass the same `resumed` for every event of that resume:
>
> ```ts events.ts theme={null}
> const text = savedCartSettled(cartEventOf(event), resumed);
> if (text) await sendSms(shopper, text);
> ```

> [tab] MCP
>
> Write both messages from the `list_carts` and `resume_cart` results. The MCP server has no text helper.

> [tab] API
>
> Write the first message from the list and the second from the resume's `changes`. The API has no text helper.

## Pull a cart into this chat

A new chat starts with no cart. A cart only moves to another chat when the shopper pulls it, so nothing they saved in a private chat shows up in a group on its own.

The shopper can pull a cart by asking in their own words, such as "bring back my cart from earlier". Agentcard lists their carts from other chats, and the one they pick moves to the chat they wrote in and is priced again:

```text theme={null}
You have 2 saved carts from other chats:
1. Rocket Dog + Amazon: Miette Sneaker, USB-C cable. Saved Nov 14
2. DoorDash: 2 items from Tacos El Gordo. Saved today
Which one should I bring here?
```

Your app can pull one too, from its own list. The cart moves rather than copying, so it can only be paid once, and the chat it left reads "This cart moved to another chat, and continues there." A pulled cart takes everything with it, so the shopper's yes in the new chat pays every store in it, Amazon, DoorDash and a flight included.

A shopper who asks for one product of a saved cart, such as "get me those tumblers again", gets only that product's store. That store's part moves to the chat they wrote in and is priced again, and every other store stays saved where it was. A store moves whole, with every product it holds there. To bring the rest, the shopper asks for the whole cart.

A cart whose payment is under way in another chat stays there, and the pull is refused with `cart_paying`. Let the payment finish in that chat. A chat that already holds its own cart with the same seller refuses the pull with `store_cart_here`: a second Amazon or Walmart cart, a second DoorDash cart, or a second flight, hotel or booking with the same seller. The shopper finishes or clears the cart in this chat first, or keeps the saved one in its own chat. A store whose checkout Agentcard fills in itself, such as a Shopify store, holds a cart in each chat, so two of its carts can share one chat.

> [tab] SDK
>
> ```ts carts.ts theme={null}
> const { carts } = await agentcard.listCarts({ externalUserId: shopper.id });
> const elsewhere = carts.filter((c) => c.threadId !== chat.id); // e.g. "Rocket Dog + Amazon", saved Nov 14
> const resumed = await agentcard.bringCart(elsewhere[0].id, { externalUserId: shopper.id }, { threadId: chat.id });
> ```
>
> `resumed.moved` names the chat the cart came from, or reads `null` when it was already here. A refused pull throws:
>
> ```text theme={null}
> AgentcardApiError: cart_paying
> ```

> [tab] MCP
>
> The MCP server has no tool that moves a cart. The shopper pulls one by asking in their own words, and your model sends that message with [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) in the chat they wrote in.

> [tab] API
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/bring \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42", "thread_id": "group-chat-7" }'
> ```
>
> ```json theme={null}
> {
>   "cart": { "id": "cart_410e3cdfb197971262a3afd3", "conversation_id": "conv_d4b9defeec76c88e350272b4", "thread_id": "group-chat-7", "state": "ready", "version": 11, "lines": [ ... ] },
>   "changes": [
>     { "key": "amazon", "route": "retail", "outcome": "ready", "before_cents": 1085, "now_cents": 1085 }
>   ],
>   "moved": { "from_thread_id": null }
> }
> ```
>
> The cart now lives in a new conversation in that chat, under the new `conversation_id`. `moved.from_thread_id` names the chat it came from, `null` here for a cart that had no chat id, and `moved` reads `null` when the cart was already in that chat. A refused pull answers:
>
> ```text theme={null}
> 409
> {
>   "error": "This cart's payment is under way in the chat that holds it, so it stays there.",
>   "code": "cart_paying"
> }
> ```

## Send the yes to the cart

Send the shopper's next message to the saved cart, so their words and their yes go to it. Agentcard answers with the cart as it stands now, says what changed since the shopper saved it, and asks for a yes at that price.

The shopper's yes then confirms that cart, as any purchase does. Stop sending the cart's id once no saved cart is open.

> [tab] SDK
>
> Build the buy tool with the cart's id:
>
> ```ts chat.ts theme={null}
> const buy = buyTool({ agentcard, externalUserId: shopper.id, cartId: cart.id });
> ```
>
> Leave `cartId` out once no saved cart is open.

> [tab] MCP
>
> The `buy` tool takes no cart id. It answers the open purchase of the `shopper_id` and `thread_id` you send, so send the shopper's message with [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) in the chat that holds the cart, and `confirm: true` only on their yes.

> [tab] API
>
> Send `cart_id` with the shopper's message:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "cart_id": "cart_410e3cdfb197971262a3afd3",
>     "thread_id": "group-chat-7",
>     "external_user_id": "user-42",
>     "ask": "yes, buy it"
>   }'
> ```
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "conversation_id": "conv_d4b9defeec76c88e350272b4",
>   "reply": "Price dropped since you saved it. Here's the cart as it stands now:\n\n1× Amazon Basics 20-Pack AA Alkaline Batteries from Amazon, now $9.99 (was $10.85). With fees, the estimated total is $10.24. It ships to 1 Market St, San Francisco, CA 94105.\n\nSay yes to place it at this price.",
>   "next_action": "confirm",
>   "cart": { "totalCents": 1024, "hash": "ad9cdf1a1a5037ab", ... }
> }
> ```
>
> The yes is a confirm with the cart's `hash`, a short code that names this exact cart at this price, and the `conversation_id` the answer gave, as [Buy over HTTP](https://docs.agentcard.com/purchase-api/http.md#confirm-the-cart) shows. `cart_id` finds the conversation itself, so Agentcard refuses it beside `conversation_id`, `resume` or `new_order`:
>
> ```text theme={null}
> 400
> {
>   "error": "`cart_id` finds the conversation itself: send it without `conversation_id`, `resume` or `new_order`",
>   "code": "invalid_request"
> }
> ```
>
> Send `cart_id` alone.

## Start the price check early

Tell Agentcard the shopper came back as soon as they open the chat, before they open the cart. The slow stores start pricing then, so the resume answers sooner.

> [tab] SDK
>
> ```ts carts.ts theme={null}
> await agentcard.warmCart(cart.id, { externalUserId: shopper.id });
> ```

> [tab] MCP
>
> [`get_cart`](https://docs.agentcard.com/commerce-mcp/tools/get_cart) starts the stores' pricing each time you call it, so a `resume_cart` right after answers sooner. There is nothing extra to call.

> [tab] API
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/warm \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42" }'
> ```
>
> ```json theme={null}
> { "cart_id": "cart_410e3cdfb197971262a3afd3", "warming": true }
> ```
>
> The call answers `202` at once.

## Change a cart

Set one item's quantity, or take a whole store out, at the cart `version` you read. Each change answers the cart with its new `version`. A quantity of `0` takes the item out, and a cart left with no store ends. Change a cart only when the shopper asked.

A change reaches a store whose checkout Agentcard fills in itself, and most such stores price the changed line again at the next resume. A Shopify store's line comes back `failed` with `edited_waits_for_store`, since its checkout still holds the old count: the shopper adds the item again at the new count.

A line at a large store such as Amazon, Walmart or Target, at DoorDash, or for a flight, a hotel, a car, a table or tickets follows the shopper's own cart at that seller, so the change is refused with `line_not_editable`. The shopper makes that change by asking in their chat.

A change sent with an older `version` is refused with `cart_changed`, and the cart as it stands comes back with the refusal. Show the shopper that cart, and send their change again with its `version`.

> [tab] SDK
>
> ```ts edit.ts theme={null}
> const edited = await agentcard.setCartQuantity(cart.id, line.key, { version: cart.version, quantity: 3 }, { externalUserId: shopper.id });
> await agentcard.removeCartStore(edited.id, otherLine.key, edited.version, { externalUserId: shopper.id });
> ```
>
> A refused change throws, and the cart as it stands is in `error.body.cart`:
>
> ```text theme={null}
> AgentcardApiError: cart_changed
> ```

> [tab] MCP
>
> Call [`update_cart_line`](https://docs.agentcard.com/commerce-mcp/tools/update_cart_line) with the item's place in the line, counting from `0`:
>
> ```json theme={null}
> {
>   "tool": "update_cart_line",
>   "arguments": { "shopper_id": "user-42", "cart_id": "cart_410e3cdfb197971262a3afd3", "line_key": "rocketdog.com", "version": 9, "item": 0, "quantity": 3 }
> }
> ```
>
> The result is the cart, in the shape `get_cart` returns. Take a whole store out with [`remove_cart_store`](https://docs.agentcard.com/commerce-mcp/tools/remove_cart_store), which takes `line_key` and `version`. A refused change returns:
>
> ```json theme={null}
> { "error": { "code": "cart_changed", "message": "...", "retryable": false } }
> ```
>
> Call `get_cart` and make the change again on its `version`. To take one item out of a purchase still in progress, not a saved cart, use [`remove_cart_line`](https://docs.agentcard.com/commerce-mcp/tools/remove_cart_line).

> [tab] API
>
> The path names the store's line by its `key`, and `item` is the item's place in the line's `items`, counting from `0`:
>
> ```bash theme={null}
> curl -X PATCH https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/lines/rocketdog.com \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42", "version": 9, "item": 0, "quantity": 3 }'
> ```
>
> Take a whole store out at the new version:
>
> ```bash theme={null}
> curl -X DELETE "https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/lines/rocketdog.com?version=10" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42" }'
> ```
>
> A change at an older version answers:
>
> ```text theme={null}
> 409
> {
>   "error": "The cart changed since this version was read. Read it again and send the edit with its current version.",
>   "code": "cart_changed",
>   "cart": { "id": "cart_410e3cdfb197971262a3afd3", "version": 9, ... }
> }
> ```
>
> A line that follows the shopper's own cart at the seller answers:
>
> ```text theme={null}
> 409
> {
>   "error": "This store's line follows the shopper's cart at the store, so it changes there, through the shopper's chat, never through this edit.",
>   "code": "line_not_editable",
>   "cart": { ... }
> }
> ```

## Set a gift's arrival day

Set the latest day every line should arrive by, and a gift note of up to 240 characters. Nothing is priced or paid. At the shopper's next yes, each store's own delivery estimate is read against the day: a line that arrives late is named before the approval and left out of it, unless the shopper keeps it anyway. A new day clears the late lines the shopper kept.

A cart being approved or paid refuses the change with `cart_approving`, and a chat where a purchase is still running refuses it with `turn_in_progress`. Send the change again once that ends.

> [tab] SDK
>
> ```ts gift.ts theme={null}
> const delivery = await agentcard.setCartDelivery(cart.id, { arriveBy: '2026-12-20', giftNote: 'Happy holidays!' }, { externalUserId: shopper.id });
> ```
>
> Pass `keepLate` with the keys of late lines the shopper keeps, and `null` to clear the day or the note. The answer carries the cart's new `version`.

> [tab] MCP
>
> Call [`set_cart_delivery`](https://docs.agentcard.com/commerce-mcp/tools/set_cart_delivery):
>
> ```json theme={null}
> {
>   "tool": "set_cart_delivery",
>   "arguments": { "shopper_id": "user-42", "cart_id": "cart_410e3cdfb197971262a3afd3", "arrive_by": "2026-12-20", "gift_note": "Happy holidays!" }
> }
> ```
>
> ```json theme={null}
> { "cart_id": "cart_410e3cdfb197971262a3afd3", "version": 10, "arrive_by": "2026-12-20", "gift_note": "Happy holidays!", "keep_late": [] }
> ```
>
> Pass `keep_late` with the `line_key` of each late line the shopper keeps.

> [tab] API
>
> ```bash theme={null}
> curl -X PUT https://api.agentcard.sh/buy/carts/cart_410e3cdfb197971262a3afd3/delivery \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "external_user_id": "user-42", "arrive_by": "2026-12-20", "gift_note": "Happy holidays!" }'
> ```
>
> ```json theme={null}
> { "cart_id": "cart_410e3cdfb197971262a3afd3", "version": 10, "arrive_by": "2026-12-20", "gift_note": "Happy holidays!", "keep_late": [] }
> ```
>
> `keep_late` is the whole list of late lines the shopper keeps, by their `key`. A field you leave out keeps its value.

## Hand a store to your agent

When your company's own agent checks out at a store instead of Agentcard, Agentcard never reaches that store's checkout. A resumed line for such a store reads `changed` with reason `listed_price`: the new total is the price the store lists, before tax and shipping. The line reads that way even when the price did not move, because only your agent's checkout reads the store's total.

The change carries `handoff`, a new link your agent opens to buy, like the one it got for the first purchase. It names the store, the product, how many to buy, the listed price of one, and when the link stops working for this purchase.

The shopper approves the store's real total when your agent's checkout reaches payment. A product the store no longer lists reads `unavailable` with `offer_gone`, and carries no link.

> [tab] SDK
>
> `change.handoff` holds `buyUrl`, `store`, `product`, `quantity`, `listedPrice` and `expiresAt`:
>
> ```ts resume.ts theme={null}
> for (const change of resumed.changes) {
>   if (change.handoff) await myAgent.checkout(change.handoff.buyUrl, change.handoff.quantity); // your code
> }
> ```
>
> `resumeCartAsText` tells the shopper so and asks them for no yes:
>
> ```text theme={null}
> Today's prices:
> • Woolzies: listed at $29.98 before tax and shipping
> You'll see the store's total before you pay.
> ```
>
> When your company registered a browser of its own for Agentcard to drive, the resume runs the store's checkout again in that browser, and the line reads like any other store's.

> [tab] MCP
>
> A `resume_cart` change carries no `handoff` link, so a store your own agent checks out is not handed back through the MCP server.

> [tab] API
>
> The change's `handoff` holds `buy_url`, `store` (its `domain` and `name`), `product` (its `id` and `title`), `quantity`, `listed_price` (`amount_cents` and `currency`) and `expires_at`.

## Know how long a cart lasts

A cart lasts as long as its longest-lived store line, counted from that store's last price. The cart's `expires_at` says when.

| Store line | Lasts |
| - | - |
| A store's product, Amazon, Walmart and Target included | 7 days |
| A meal delivery, a table or a class | 4 hours |
| Tickets or a flight | Until the seller's offer expires, or 30 minutes when it names none |
| A hotel or a car | Until the seller's quote expires, or 15 minutes when it names none |

A cart that ran out of time, was placed or was dropped leaves the list, and a resume of it is refused with `cart_ended`.

## Check it in the sandbox

The sandbox is Agentcard's test mode, which charges nothing.

1. As a test shopper, ask for "a pack of AA batteries from amazon", pick one, and stop at the cart's total without approving.
2. List the shopper's carts. Check that the cart lists Amazon with the total you saw.
3. Price the cart again. Check that Amazon's change reads `ready`, `changed`, or `needs_input` with `address_needed`, and that the total before is the one you saw.
4. Change the Amazon line with a `version` lower than the cart's. Check that it is refused with `cart_changed`.
5. Over the SDK or the API, pull the cart into a new chat id. Check that `moved` is set and the cart names the new chat.


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