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

# Move the purchase on

> Move a purchase on the moment a shopper saves a card, signs in to a store or declines an approval, without waiting for them to type ok.

Some steps of a purchase happen outside your chat. The shopper saves a card from the add-a-card link, signs in to DoorDash from the sign-in link, or declines the payment on the approval page. Agentcard tells your app the moment each one ends.

If your app only posts Agentcard's message, the shopper reads "Your Visa ending 4242 is saved, so you're ready to check out." and then has to type "ok" before anything moves. Take the next step for them instead, and the shopper reads one message that does the next thing: the approval link, the add-a-card link, or the total and a request for their yes.

## Hear when a step ends

Three kinds of message end a step the shopper took outside the chat. Take the next step for these three, and post the message's `text` as it is for every other kind, such as `order_placed`, whose `text` is already the whole message.

| `kind` | What happened |
| - | - |
| `card_added` | The shopper saved a card in the Vault, Agentcard's page where they keep their card, or picked one they already keep. |
| `store_connected` | The shopper signed in to their own account at the store the message names. |
| `approval_declined` | The shopper said no on the approval page. Nothing was charged. |

A message whose `advances` is true is one of these three.

> [tab] SDK
>
> The messages arrive in `onMessage`, through `listen` or the webhook handler. `NEXT_STEP_KINDS` lists the three kinds that advance, and `buy.nextStep(message)` in the next section picks them out.

> [tab] MCP
>
> Call [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates) with the shopper's `shopper_id` and the chat's `thread_id`. The first call only starts following and returns nothing, so call it once early, then again whenever you check in.
>
> ```json theme={null}
> {
>   "tool": "get_updates",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "limit": 50,
>     "time_zone": "America/Los_Angeles"
>   }
> }
> ```
>
> Each message in `messages` carries `kind`, `text`, `advances`, `links` and `valid_until`. Skip a message whose `valid_until` has passed.

> [tab] API
>
> Each message arrives as a `purchase.message` webhook, a request Agentcard sends to your server when something happens. Register a webhook endpoint, the URL on your server that receives these requests, and list the event by name. A catch-all `["*"]` alone does not include `purchase.message`, so name it, or name `purchase.*`.
>
> ```bash theme={null}
> curl https://api.agentcard.sh/api/v2/webhook_endpoints \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "url": "https://your.app/agentcard/webhooks", "enabled_events": ["purchase.message"] }'
> ```
>
> [Webhooks](https://docs.agentcard.com/webhooks/overview.md) covers the endpoint's secret, checking the signature on each request, and retries. Agentcard can deliver an event more than once, so handle each event `id` once.
>
> ```json theme={null}
> {
>   "id": "evt_...",
>   "type": "purchase.message",
>   "created": 1795122147,
>   "livemode": true,
>   "data": {
>     "kind": "card_added",
>     "user_id": "usr_...",
>     "external_user_id": "user-42",
>     "text": "Your Visa ending 4242 is saved, so you're ready to check out.",
>     "note": "[event: this user just saved their Visa ending 4242 in Agentcard from the card link, outside this conversation, so a purchase can be paid with it now. Nothing more is needed from the user for the card. This note was generated by the system, not typed by the user.]",
>     "facts": { "card_brand": "visa", "card_last4": "4242" },
>     "connection": { "client_id": "...", "scope": "user_connection" }
>   }
> }
> ```
>
> `external_user_id` is your own id for the shopper. `note` says the same as `text` for your own language model, marked as written by Agentcard and not typed by the shopper.
>
> `card_added` and `store_connected` carry no `conversation_id`, because the card and the sign-in belong to the shopper, not to one purchase. A shopper can keep one purchase open in a private chat and another in a group, so save a purchase's `conversation_id` beside your id for the chat whenever a confirm asks for a card or a sign-in, and follow up with the pair you saved. `approval_declined` carries its `conversation_id`.

## Confirm the yes they gave

Pick the next step by what the shopper said before they left the chat:

| Before the step, the shopper | The next step |
| - | - |
| Said yes to the cart, and that yes stopped for a card or a sign-in | Confirm the same cart again, passing on their earlier yes. |
| Picked the product in the cart, and answered only the checkout's questions since | Confirm the same cart, passing on their pick. |
| Neither | No confirm. Show the cart's total and ask for their yes. |

A confirm sends the shopper's yes for one exact cart, named by its hash: a short code that changes when anything in the cart changes. A cart that changed while the shopper was away is not paid, and the shopper is asked again. The approval page stays the shopper's own consent: it names the most they can be charged, and Agentcard places the order only once they approve there.

Never send words of your own as the shopper's message on this step. Agentcard reads a shopper message as the shopper's words, so text your app or your model wrote could read as a yes the shopper never gave.

> [tab] SDK
>
> Call `buy.nextStep(message)`. It returns a turn, the buy tool for one run of your model, or null when there is no step to take. Run your model on the turn without awaiting it in the listener, and run one shopper's turns in order.
>
> ```ts server.ts theme={null}
> import type { BuyToolTurn } from '@agent-cards/commerce-sdk';
> import { agentcard, buyFor } from './agentcard';
>
> const runs = new Map<string, Promise<void>>();
>
> agentcard.listen({
>   onMessage: (shopperId, message) => {
>     const step = buyFor(shopperId).nextStep(message);
>     if (!step) return postToChat(shopperId, message.text);
>
>     const run = (runs.get(shopperId) ?? Promise.resolve())
>       .then(() => runModel(shopperId, step))
>       .catch(async () => {
>         // The turn failed: release it so its text reaches later turns, and post the text instead.
>         step.release();
>         await postToChat(shopperId, message.text);
>         agentcard.delivered(shopperId, message); // only once the post went out
>       })
>       // The fallback post failed as well, so nothing is recorded and a redelivery opens the turn again.
>       .catch(() => {});
>     runs.set(shopperId, run);
>   },
> });
>
> async function runModel(shopperId: string, turn: BuyToolTurn) {
>   const runner = anthropic.beta.messages.toolRunner({
>     model: 'claude-opus-5-5',
>     max_tokens: 16000,
>     tools: [turn],
>     messages: turn.messages(histories.get(shopperId)),
>   });
>   const answer = await runner;
>   histories.set(shopperId, runner.params.messages);
>   await postToChat(shopperId, textOf(answer), turn.links);
> }
> ```
>
> `anthropic`, `histories`, `postToChat` and `textOf` stand for your own code. `turn.messages(history)` ends with the event, marked as written by the system, and the instruction to take the next step in one short message. Post the model's answer in place of `message.text`.
>
> The tool holds the shopper's decision whatever the model calls. No call of the turn sends an ask to Agentcard. A confirm goes in only for the go-ahead the shopper already gave, once, for that cart's hash. Any other confirm the model sends is refused by the tool, and nothing reaches Agentcard. A shopper message after the go-ahead that is not a plain go-ahead, such as "wait, make it two", takes it back. A shopper who was not connected yet when they first asked gets that first ask run, in their own words, once their card is saved.
>
> After a pick, the model reads `yes_carried` with `picked: true` and never asks for the yes again. With `direct: true` and `replyAsWritten: true`, the turn's call goes straight to Agentcard and `turn.replyAsWritten` is a fixed short line, so the turn needs no model call. [Read the step lines](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool.md#read-the-step-lines) lists the lines.

> [tab] MCP
>
> The MCP server takes the step for you. When a message's `advances` is `true` and you passed `thread_id` to `get_updates`, the next step runs on its own, with the same rules as the table above. When `next_step.outcome` reads `ran`, tell the shopper what `next_step.result` says, with its links, instead of `text`, and do not ask them to say done.
>
> If the shopper tells you they finished before `get_updates` reports it, call `buy` again in the same chat. Set `confirm: true` only when the shopper said yes to the cart, as [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) says.

> [tab] API
>
> Read the conversation first. The answer lists each cart with its `hash`.
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/conversations/conv_0758c600dc272b6abdbc5e5e?external_user_id=docs-guide-links-2" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "conversation_id": "conv_0758c600dc272b6abdbc5e5e",
>   "status": "open",
>   "turn_in_progress": false,
>   "last_checkout": null,
>   "orders": [],
>   "carts": [
>     {
>       "merchant": "doordash",
>       "merchant_name": "DoorDash",
>       "store": { "id": "270561", "name": "Chipotle Mexican Grill" },
>       "items": [ { "name": "Burrito", "qty": 1, "priceCents": 1535, "options": ["Chicken"], ... } ],
>       "totalCents": 1573,
>       "totalIsEstimate": true,
>       "hash": "d2af60c58141488c"
>     }
>   ],
>   ...
> }
> ```
>
> `turn_in_progress: true` means a call for this shopper is still running, so wait for its answer instead. `orders` lists any order already placed, and `last_checkout.approval_url` holds an approval link the shopper still has open.
>
> Send the cart's current `hash` in `confirm`, and the hash the shopper said yes to in `carried`. `from` is `yes` for their yes, or `pick` for their pick. Send no `ask`.
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "conversation_id": "conv_0758c600dc272b6abdbc5e5e",
>     "external_user_id": "docs-guide-links-2",
>     "confirm": "d2af60c58141488c",
>     "payment_source": "vault",
>     "carried": { "from": "yes", "cart_hash": "d2af60c58141488c" }
>   }'
> ```
>
> `payment_source: "vault"` pays with the card the shopper saved in the Vault. The answer carries the approval link with `next_action: "approve"`, as [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) shows.
>
> A cart that changed since the yes is not paid. Agentcard answers `200` with the cart as it stands now, `next_action: "confirm"`, and a `reply` that asks again:
>
> ```json theme={null}
> {
>   "conversation_id": "conv_ce02ab2f6155fad3b8232cbd",
>   "status": "needs_input",
>   "reply": "The cart changed after your yes: Amazon Basics 8-Pack AA Alkaline High-Performance Batteries, ... comes to an estimated $13.30 now, with tax and delivery confirmed at checkout. Nothing was paid. Say yes to go on with it.",
>   "next_action": "confirm",
>   "cart": { "totalCents": 1330, "totalIsEstimate": true, "hash": "c7e5b3ca1da0b361", ... }
> }
> ```
>
> Post that `reply`, and confirm the new `hash` on the shopper's next yes. A cart that is gone altogether is refused, and nothing is paid:
>
> ```text theme={null}
> 409
> {
>   "error": "This confirm names another cart than the one the shopper said yes to, and that cart is no longer open. Nothing was paid. Read the conversation's carts, show the shopper the one that stands, and confirm it on their yes.",
>   "code": "cart_changed",
>   "conversation_id": "conv_..."
> }
> ```
>
> Read the conversation again, show the shopper the cart as it stands now, and confirm its hash on their yes.

## Answer a declined approval

An `approval_declined` message means the shopper said no to the payment. Nothing was charged, and the cart stays in the conversation. Send no confirm. Tell the shopper so, and offer a new approval:

```text theme={null}
You declined the payment, so you haven't been charged. Your burrito is still in the cart: say yes if you want a new approval link, or tell me what to change.
```

On the shopper's yes, confirm the cart's current hash as a fresh yes. The answer carries a new approval link.

> [tab] SDK
>
> The turn from `buy.nextStep` writes this message for you.

> [tab] MCP
>
> `next_step.result` from `get_updates` carries this message. On the shopper's yes, call `buy` with `confirm: true`.

> [tab] API
>
> On the shopper's yes, send a confirm with the cart's current `hash` and no `carried`, since the shopper gave this yes just now.

## Know what the shopper reads next

| The shopper finished | The next message |
| - | - |
| Saving a card, after a yes that stopped for it | The approval link: `i sent you a link to approve the payment for your chicken salad. it works for about 15 minutes, and the most you'll be charged is $19.02.` |
| Saving a card, after they picked what is in the cart | The approval link, with no second request for a yes: `approve the payment to place your order (up to $19.02)` |
| Saving a card, with no yes and no pick | The total and a request for the yes: `your Souvla chicken salad comes to $17.43 with fees. should i go ahead and place the order?` |
| Signing in to the store, with a card still to save | The add-a-card link: `next, add a card with the link i sent. it works for about 24 hours.` |
| Signing in to the store, with a card saved | The approval link after a yes, or the total and a request for their yes. |
| Declining the approval | Nothing was charged, the cart is kept, and a yes brings a new approval link. |

A total that moved because the store priced its fees and tax opens the line with the new total, such as `it's $17.89 with fees and tax now. approve the payment to place your order (up to $19.02)`. Post this one message in place of the event's `text`, so the shopper reads one message, not two.

## Handle a message with no step

> [tab] SDK
>
> `buy.nextStep` returns null in four cases, and your code posts `message.text` then:
>
> * The message's `advances` is false.
> * The message is for another shopper, or its link closed.
> * The tool already took a turn for the message.
> * The message arrives while a call for the shopper's own message is still running. That call's answer tells the model where the purchase stands.
>
> When your agent cannot finish the turn, call `step.release()` before you post `message.text`, as the code above does. The text then reaches later turns once `agentcard.delivered` records it, and a redelivery of the event opens a turn again.
>
> The client keeps each message in memory, at most 20 for each shopper, so the listener and the turn run in one process on one client. When your model runs elsewhere, such as a serverless chat route, keep each message in your chat history as an assistant message, and the model reads it from there.

> [tab] MCP
>
> When `advances` is `false`, or `next_step.outcome` is not `ran`, post the message's `text` with its links as they are.

> [tab] API
>
> For any other `kind`, post `text` as it is. When the conversation reads `turn_in_progress: true`, make no call and wait for the running call's answer.

## Check it before you go live

The sandbox, Agentcard's test mode, sends no `card_added`, `store_connected` or `approval_declined` message, so test the follow-up with a message you send yourself, then once with live credentials.

> [tab] SDK
>
> 1. Pass a `card_added` message to your `onMessage` from a test of your own. Check that the chat posts one message that does the next thing, with nothing typed after it.
> 2. Make your model throw during `runModel`. Check that the shopper still reads `message.text`.
> 3. With live credentials, ask for a sandwich, pick one, answer the address, and save a card from the Vault link. Check that the next message is the approval link with no second request for your yes.

> [tab] MCP
>
> 1. With live credentials, buy one inexpensive item as a shopper with no card saved, passing `thread_id` to `get_updates`.
> 2. Save the card from the add-a-card link without typing in the chat. Check that `get_updates` returns a message with `next_step.outcome: "ran"` and the approval link.

> [tab] API
>
> 1. Send the event above to your own webhook handler from a test of your own, with the signature check turned off for that test. Check that your app reads the conversation and makes the right follow-up call.
> 2. In the sandbox, put an item in a cart, then send a confirm whose `carried.cart_hash` is a hash the shopper never saw, such as `0123456789abcdef`. Check that the answer reads `next_action: "confirm"` with a `reply` that starts "The cart changed after your yes".
> 3. With live credentials, buy one inexpensive item as a shopper with no card saved. Save the card without typing in the chat, and check that the chat posts the approval link on its own.


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