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

# Read a refusal, take a next step

> Every error code a purchase call can get, what it means, and the one change that gets the purchase going again.

When Agentcard cannot do what a call asks, it refuses with a `code` that names what went wrong. A refusal charges nothing, and the message says so whenever a payment was about to happen. Read `code` to decide what to do next. The wording of the message is written for you to read and can change, so never match on it.

A refusal is different from a declined purchase. A purchase Agentcard tried and could not finish is an answer, not an error: its status is `declined`, a `decline_code` says why, and `reply` explains it to the shopper. [Read a declined answer](#read-a-declined-answer) covers those.

## See how a refusal arrives

The codes are the same in the SDK, the MCP server and the API. Only the way a refusal reaches your code differs.

> [tab] SDK
>
> A call on `AgentcardClient`, such as `agentcard.conversation()` or `agentcard.order()`, throws an `AgentcardApiError`:
>
> | Property | What it holds |
> | - | - |
> | `code` | The code from the table below. Branch on it. |
> | `status` | The HTTP status, or `0` when Agentcard never answered. |
> | `body` | The error body as Agentcard sent it, the same body the examples on this page show. |
> | `conversationId` | The conversation the refusal names, or `null`. |
> | `carts` | The carts as they stand, when the refusal names them. A changed cart's new hash is here. |
>
> ```ts orders.ts theme={null}
> import { AgentcardApiError } from '@agent-cards/commerce-sdk';
>
> try {
>   return await agentcard.order(orderId, { externalUserId: shopper.id });
> } catch (error) {
>   if (error instanceof AgentcardApiError && error.code === 'order_not_found') return null;
>   throw error;
> }
> ```
>
> The buy tool answers some refusals for the model instead of failing. `cart_changed`, `nothing_to_confirm`, `conversation_closed`, a changed delivery address, `cart_not_ready`, `turn_in_progress`, `pick_not_found` and `store_pick_not_found` come back as `status: 'needs_input'`, with the code in `error_code` and a `reply` that tells the model what to do:
>
> ```ts theme={null}
> {
>   status: 'needs_input',
>   reply: 'There is no cart to confirm yet. Ask the shopper what they want.',
>   error_code: 'nothing_to_confirm',
>   ...
> }
> ```
>
> A shopper not yet connected to your company comes back as `status: 'needs_card'`, with the link to add a card. Every other refusal fails the tool call: your model reads the message with its links taken out, and the error's `cause` holds the `AgentcardApiError`.
>
> The client adds codes of its own, for a call that never got an answer it can read:
>
> | `code` | What it means | What to do next |
> | - | - | - |
> | `oauth_failed` | Agentcard refused your client ID and secret. | Check `clientId` and `clientSecret`. |
> | `unauthorized` | Agentcard refused the access token. | Sign the shopper in again when the token was their own. |
> | `timeout` | No answer came in time, so whether the call ran is unknown. A purchase call waits 130 seconds. | Read the conversation with `agentcard.conversation()`. Send the call again only once that read shows it did not finish. |
> | `unreachable` | No answer came back. The request can still have reached Agentcard. | Act as for `timeout`. |
> | `invalid_answer` | Agentcard answered with a body the client cannot read. | Act as for `timeout`. |
> | `http_<status>` | Agentcard answered with a status that carries no code, such as `http_502`. | Retry later, or read the conversation first when the call was a purchase message. |
>
> On this page, `external_user_id` is the `externalUserId` you pass, and `conversation_id` is the answer's `conversation_id`.

> [tab] MCP
>
> The `buy` tool answers some refusals instead of failing, as the SDK's buy tool does. `cart_changed`, `nothing_to_confirm`, `conversation_closed`, a changed delivery address, `cart_not_ready`, `turn_in_progress`, `pick_not_found` and `store_pick_not_found` come back as a normal result with the code in `error_code`. A confirm with no cart in the chat answered:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "There is no cart to confirm yet. Ask the shopper what they want.",
>   "next_action": null,
>   "conversation_id": null,
>   "decline_code": null,
>   "error_code": "nothing_to_confirm",
>   ...
> }
> ```
>
> Every other refusal comes back in the tool result in this shape. A `get_order` call with an `order_id` Agentcard does not know answered:
>
> ```json theme={null}
> { "error": { "code": "order_not_found", "message": "order_id not found", "retryable": false } }
> ```
>
> Branch on `code`, never on `message`. Send the same call again only when `retryable` is `true`. After an unclear write, read the state first, as [Read before you retry](https://docs.agentcard.com/commerce-mcp/index.md#read-before-you-retry) shows.
>
> The server adds codes of its own:
>
> | `code` | What it means | What to do next |
> | - | - | - |
> | `unauthorized` | Agentcard refused the client ID and secret. A request with none gets HTTP `401`. | Fix the `Authorization` header. |
> | `busy` | Another `buy` runs for this shopper and chat, and nothing was sent. | Read `get_conversation`, then continue. |
> | `invalid_input` | The arguments do not match the tool. | Fix the arguments. Do not send the same call again. |
> | `rate_limited`, `timeout`, `upstream_unavailable`, `upstream_error` | The call did not finish. | Retry a read after a short wait. For a write, read the state first. |
> | `turn_timeout` | In `error_code` beside `turn_continues: true`: Agentcard is still working. | Tell the shopper you are on it, and read `get_conversation` or `get_updates` later. |
> | `stats_not_available` | Purchase stats are not on for your company. | Do not retry. |
> | `order_actions_unavailable` | Cancels and returns are not on yet. | Tell the shopper to contact the store, or check the order with `get_order`. |
>
> On this page, `external_user_id` is your `shopper_id`, `thread_id` is your `thread_id`, and a pick is the `product_id` or `store_id` you send. Your server fills in the two ids, so the refusals about them point to a bug in that code.

> [tab] API
>
> A refusal is an HTTP error status and a JSON body whose `code` names what went wrong:
>
> ```text theme={null}
> 409
> {"error":"nothing to confirm. No cart has been shown in this conversation yet","code":"nothing_to_confirm","conversation_id":"conv_ddaaf96c052893b13209e6c9"}
> ```
>
> Three answers carry no `code`. An expired or wrong access token gets `401`:
>
> ```text theme={null}
> 401
> {"error":"Invalid or expired token"}
> ```
>
> Get a new token, as [Get an access token](https://docs.agentcard.com/purchase-api/http.md#get-an-access-token) shows. A token lasts an hour.
>
> Too many calls get `429`:
>
> ```text theme={null}
> 429
> {"error":"Too many requests, please try again later"}
> ```
>
> Each shopper gets 300 calls in 15 minutes, and your app 3,000 across all its shoppers. Wait, then send the call again.
>
> `GET /buy/merchants` has refusals of its own, which [Check where Agentcard can pay](https://docs.agentcard.com/opencommerce/guides/checking-where-agentcard-can-pay.md) shows.

## Find the code

Each code has its own section below, with the body as the API sends it. Two words recur: a conversation is one purchase, from the shopper's first request to the order, and a cart's `hash` is a short code that names this exact cart at this price, which a confirm sends back.

| Code | HTTP status | What it means | What to do next |
| - | - | - | - |
| `user_id_required` | 400 | The call did not say which shopper it is for. | Send `external_user_id` on every call. |
| `user_not_connected` | 403 | No shopper of your app in this mode, sandbox or live, carries that `external_user_id`. | Start the shopper with a purchase request that carries what they asked for. |
| `user_id_conflict` | 400 | The call sent both `user_id` and `external_user_id`. | Send one of them. |
| `user_id_mismatch` | 400 | A shopper's own access token named a different shopper. | Call with your company's token to buy for someone else. |
| `invalid_external_user_id` | 400 | `external_user_id` is longer than any id Agentcard stores. | Send the id you used before for that shopper. |
| `external_user_id_ambiguous` | 409 | More than one shopper carries that `external_user_id`. | Send one of the listed `user_ids` as `user_id`. |
| `invalid_request` | 400 | A field is missing or the wrong shape. | Read `error`, which names the field. |
| `items_not_supported` | 400 | The call listed products as `items`. | Describe what the shopper wants as `ask`. |
| `invalid_delivery_address` | 400 | `delivery_address` is missing a part. | Send street, city, state and zip. |
| `invalid_return_url` | 400 | `return_url` is not one of your app's registered addresses. | Send a registered address exactly. |
| `conversation_not_found` | 404 | No conversation with that id belongs to this shopper and app. | Leave out `conversation_id` to start a new one. |
| `conversation_closed` | 409 | The conversation has ended. | Start a new conversation. |
| `thread_mismatch` | 409 | The conversation belongs to another `thread_id`. | Send the conversation that thread started. |
| `pick_not_found` | 409 | The picked product is not in the latest search. | Send the shopper's words again without the pick. |
| `store_pick_not_found` | 409 | The picked store is not in the latest store search. | Send the shopper's words again without the pick. |
| `store_not_supported` | 409 | The picked product is at a store Agentcard can only show, not buy from. | Offer the shopper another store. |
| `yes_answers_question` | 409 | The shopper's yes answered a question, not the cart. | Send the yes as the shopper's words, not as a confirm. |
| `nothing_to_confirm` | 409 | No cart was shown yet. | Get a cart, then confirm it. |
| `cart_changed` | 409 | The confirmed cart no longer matches any current cart. | Show the carts in the refusal and confirm them on a new yes. |
| `delivery_address_changed` | 409 | The address changed after the cart was built. | Send the address with the shopper's words, then confirm the new cart. |
| `cart_not_ready` | 409 | The store is still building the cart. | Wait for the cart's message, then confirm. |
| `cart_not_recorded` | 503 | Agentcard could not save the cart it showed. | Read the conversation, then confirm. |
| `payment_source_vault_required` | 409 | A cart at a store's own checkout was confirmed without `payment_source`. | Confirm again with `payment_source: "vault"`. |
| `test_card_missing` | 409 | A shopper in the sandbox, Agentcard's test mode, has no test card saved. | Have the shopper save a test card, then confirm again. |
| `checkout_expired` | 409 | The store's checkout timed out before payment. | Ask again for a fresh cart. |
| `browser_session_lost` | 409 | The store's checkout closed before payment. | Ask again for a fresh cart. |
| `checkout_opening` | 409 | The store's checkout is still opening. | Confirm again in a moment. |
| `payment_step_lost` | 409 | Agentcard could not return to the store's payment page. | Ask again for a fresh cart. |
| `total_changed` | 409 | The store's total moved after the shopper confirmed. | Ask again for a fresh cart. |
| `total_over_ceiling` | 409 | The store's total is above what the shopper approved. | Ask again, and show the shopper the new total. |
| `processor_not_recognised` | 409 | Agentcard cannot type a card into this store's payment form safely. | Offer the product at another store. |
| `store_cancels_guest_orders` | 409 | The store cancels orders placed this way. | Offer the product at another store. |
| `charge_unresolved` | 409 | The payment may have gone through. | Do not buy again until the order is confirmed. |
| `not_placed` | 409 | The store placed no order and charged nothing. | Ask again for a fresh cart. |
| `browser_live_disabled` | 409 | Your account cannot place live orders at a store's own checkout yet. | Contact Agentcard to turn them on. |
| `link_payment_invalid` | 400 | A Stripe Link confirm is missing a field. | Send `conversation_id` and all of `link_payment`. |
| `link_payment_unavailable` | 409 | Stripe Link cannot pay this cart. | Cancel the Link payment and offer the Vault, Agentcard's page for the shopper's saved card. |
| `link_amount_short` | 409 | The Link payment is below the store's total. | Ask the shopper to approve the full total. |
| `cart_total_changed` | 409 | The checkout restarted at a different total. | Ask again for a fresh cart. |
| `link_seal_not_found` | 404 | No Link approval with that id waits for this shopper. | Post to the `approval_id` the confirm returned. |
| `link_seal_answered` | 409 | That Link approval was already sent, or its payment ended. | Read the conversation for the order. |
| `link_seal_expired` | 410 | The encrypted Link approval arrived after its `seal_by` deadline. | Confirm the cart again. |
| `link_seal_invalid` | 400 | The approval was not encrypted with that approval's key. | Encrypt it again with the key the confirm named. |
| `carts_not_available` | 404 | Saved carts are not on for your app. | Leave out `cart_id`. |
| `cart_not_found` | 404 | No saved cart has that `cart_id`. | Send a `cart_id` this shopper saved. |
| `cart_ended` | 409 | The saved cart was bought or closed. | Start a new cart. |
| `order_not_found` | 404 | No order of this shopper has that `order_id`. | Send the `order_id` from `order.placed`. |
| `order_id_ambiguous` | 409 | Two stores' orders share that number. | Ask again with `merchant` set to one of the listed stores. |
| `turn_in_progress` | 409 | Agentcard is still answering the last call in this conversation. | Wait, then send the call again. |
| `turn_lock_unavailable` | 503 | Purchasing is briefly unavailable. | Retry in a few seconds. |
| `turn_failed` | 502 | Agentcard could not finish answering the call. | Send the same call again. |

A code your calls cannot cause never reaches you. A call that never sends `items` or `return_url`, for example, never meets their refusals.

## Name the shopper

Your company's credentials buy for many shoppers, so every call says which one with `external_user_id`, your own id for that shopper. A call with no shopper is refused:

```text theme={null}
400
{"error":"user_id_required","code":"user_id_required","message":"A client-credentials token buys for a connected person: send their user_id, the id the connect flow returned for them, or external_user_id, your own id for them (in the body of a POST, in the query of a GET)."}
```

Send the same id for the same shopper on every call, including calls about a purchase already under way.

A shopper who never made a purchase request in this mode is refused on every other call:

```text theme={null}
403
{"error":"user_not_connected","code":"user_not_connected","external_user_id":"docs-guide-refusals-1","message":"No person connected to your sandbox app carries the external_user_id \"docs-guide-refusals-1\". Sandbox and production users are separate: connect this person with your sandbox credentials, passing this external_user_id to the connect flow or the Vault link, then send it again."}
```

Send a purchase request with what the shopper asked for, and Agentcard adds them on that request. Shoppers in the sandbox are separate from live ones, so a shopper you tested with starts again in live mode.

A call that names the shopper twice is refused:

```text theme={null}
400
{"error":"user_id_conflict","code":"user_id_conflict","message":"Name the person once: send user_id or external_user_id, not both."}
```

Send `external_user_id` alone, or `user_id` alone.

A call made with one shopper's own access token that names another shopper is refused:

```text theme={null}
400
{"error":"user_id_mismatch","code":"user_id_mismatch","message":"Under a connection access_token or a buy_token the call runs as that token's user; user_id and external_user_id may only name them. To buy for another connected person, call with your client-credentials token and their user_id or external_user_id."}
```

Call with your company's credentials to buy for another shopper.

An `external_user_id` that two shoppers carry is refused with both of them:

```text theme={null}
409
{"error":"external_user_id_ambiguous","code":"external_user_id_ambiguous","external_user_id":"user-42","user_ids":["usr_...","usr_..."],"message":"More than one person connected to your app carries the external_user_id \"user-42\", so Agentcard cannot tell which of them to buy for and nothing ran. Send the person's user_id instead; user_ids lists the people who carry it."}
```

Send the right shopper's id from `user_ids` as `user_id`, and give each shopper their own id from then on.

## Fix the request

A field missing or in the wrong shape is refused with `invalid_request`, and `error` names the field:

```text theme={null}
400
{"error":"pick must be an object with product_id or store_id","code":"invalid_request","hint":"POST /buy { \"ask\": \"order sushi from DoorDash to my place\" }"}
```

Send `pick` as `{ "product_id": "..." }`. Other values of `error` you can meet:

```text theme={null}
400
{"error":"ask is required","code":"invalid_request","hint":"POST /buy { \"ask\": \"order sushi from DoorDash to my place\" }"}
```

```text theme={null}
400
{"error":"confirm must be a cart hash from a previous response","code":"invalid_request","hint":"POST /buy { \"ask\": \"order sushi from DoorDash to my place\" }"}
```

A list of products sent as `items` is refused:

```text theme={null}
400
{"error":"items_not_supported","code":"items_not_supported","message":"POST /buy takes the request as `ask`, in plain language. The purchase agent finds the product in its catalog and builds the cart; send what the shopper wants as `ask`.","hint":"POST /buy { \"ask\": \"a 40 oz Stanley Quencher tumbler\" }"}
```

Describe what the shopper wants in `ask`, such as `"a 40 oz Stanley Quencher tumbler"`.

A `delivery_address` missing a part is refused:

```text theme={null}
400
{"error":"invalid_delivery_address","code":"invalid_delivery_address","message":"street, city, state, zip are required; for an address in another country, send its two-letter code as country (GB, AU, DE, FR, ES, IT, MX, IN, JP, NL, BE, AT, PT, IE)","hint":"delivery_address: { \"street\": \"1900 Jefferson St\", \"city\": \"San Francisco\", \"state\": \"CA\", \"zip\": \"94123\", \"phone\": \"+14155550100\", \"name\": \"Ada Lovelace\" }"}
```

Send `street`, `city`, `state` and `zip`, and `country` for an address outside the US.

A `return_url`, the page the shopper comes back to after a step, is refused unless your app registered it:

```text theme={null}
400
{"error":"return_url must be exactly one of this client's registered redirect URIs (scheme and host compared without case, a default port dropped, the fragment ignored, path and query as registered); http only on localhost in test mode.","code":"invalid_return_url","reason":"return_url is not exactly one of the registered redirect URIs"}
```

Send one of the return addresses you registered for your app, exactly as registered.

## Continue the right conversation

A `conversation_id` that is not this shopper's is refused:

```text theme={null}
404
{"error":"conversation_id not found","code":"conversation_not_found"}
```

Check that the call names the same shopper that started the conversation, or leave out `conversation_id` to start a new one.

A conversation that has ended is refused:

```text theme={null}
409
{"error":"Conversation is closed","code":"conversation_closed","conversation_id":"conv_ddaaf96c052893b13209e6c9"}
```

Start a new purchase.

A conversation started under one `thread_id`, the id of a chat in your app, is refused under another:

```text theme={null}
409
{"error":"This conversation belongs to another thread. Send the conversation_id that thread was answered with, or resume: true with this thread_id.","code":"thread_mismatch","conversation_id":"conv_ddaaf96c052893b13209e6c9"}
```

Send the `conversation_id` that chat's own requests returned, or `resume: true` with this `thread_id`.

A pick of a product that is not in the conversation's latest search is refused, and nothing is added:

```text theme={null}
409
{"error":"The picked product is not among this conversation's latest search results any more, so nothing was added. Send the shopper's words as `ask` without `pick`, and the purchase agent searches again.","code":"pick_not_found","conversation_id":null}
```

Send the shopper's words again without the pick, and Agentcard searches again. A pick of a store answers `store_pick_not_found` the same way.

A pick of a product Agentcard can show but not buy is refused:

```text theme={null}
409
{"error":"Agentcard can't buy from shop.example.com through this connection, so that product is to look at only. Nothing was added to a cart or bought.","code":"store_not_supported","conversation_id":"conv_..."}
```

Ask the shopper to pick a product at another store.

A confirm sent when Agentcard's last message asked the shopper a question about something other than the cart is refused:

```text theme={null}
409
{"error":"The shopper's yes answers the agent's last question, which was not about the cart, so nothing was confirmed. Send the shopper's words as an `ask`.","code":"yes_answers_question","conversation_id":"conv_..."}
```

Send the shopper's yes as their words, not as a confirm, so it answers the question.

## Confirm the cart that stands

A confirm names the cart the shopper said yes to. A confirm before any cart is refused:

```text theme={null}
409
{"error":"nothing to confirm. No cart has been shown in this conversation yet","code":"nothing_to_confirm","conversation_id":"conv_ddaaf96c052893b13209e6c9"}
```

Build the cart with the shopper's words, show it to them, then confirm it.

A confirmed cart that no longer matches, because an item, a quantity, a price, a tip or a fee changed, 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_ddaaf96c052893b13209e6c9",
  "cart": { "merchant": "retail", "merchant_name": "Amazon, Walmart, Target & Best Buy", "currency": "usd", "items": [ ... ], "totalCents": 1024, "hash": "ad9cdf1a1a5037ab", ... },
  "carts": [ ... ]
}
```

Show the shopper the carts in the refusal, and confirm them on the shopper's new yes. With carts at several stores, one cart that no longer matches refuses them all, so confirm every cart you still mean to buy.

A confirm after the delivery address changed is refused:

```text theme={null}
409
{"error":"delivery_address differs from the one the cart was built for. Send it on an ask first, then confirm the cart shown for it.","code":"delivery_address_changed","conversation_id":"conv_..."}
```

Send the new address with the shopper's words, show the shopper the cart built for it, then confirm that cart.

A confirm while the store is still building 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. Agentcard sends the cart with its total in a message as soon as the store's checkout has it: show that to the shopper, and confirm once they say yes to that total.","code":"cart_not_ready","conversation_id":"conv_...","cart_building":{"store":"duralexusa.com","started_at":"2026-11-19T21:04:29.116Z"}}
```

Wait for the message with the cart's total, show it to the shopper, and confirm on their yes.

Agentcard does not send an answer whose cart it could not save, and refuses instead:

```text theme={null}
503
{"error":"Agentcard could not record the cart this answer shows, so it held the answer back and nothing was confirmed. Read the conversation again with `GET /buy/conversations/:id` for the cart, then confirm it.","code":"cart_not_recorded","conversation_id":"conv_..."}
```

Read the conversation, show the shopper its cart, then confirm that cart.

## Pay at a store's checkout

Some stores are bought through their own checkout page, which Agentcard fills in. The shopper pays there with the card saved in the Vault, Agentcard's page where the shopper saves their card and approves a payment. A confirm of such a cart without `payment_source` is refused:

```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_2186d756abba3ae376fc6446"}
```

Send the same confirm with `"payment_source": "vault"`.

In the sandbox, a shopper with no test card saved is refused at the confirm:

```text theme={null}
409
{"error":"This is a test checkout, and it needs a test card on file for this shopper, which there isn't. The cart at duralexusa.com is still held at $28.36, and nothing was charged.","code":"test_card_missing","conversation_id":"conv_2186d756abba3ae376fc6446"}
```

Send the shopper a link to the Vault, have them save a test card, and confirm again. [Test in the sandbox](https://docs.agentcard.com/opencommerce/guides/testing-in-the-sandbox.md#save-a-test-card) shows the steps.

The store's checkout can end before the payment. Each of these refusals means nothing was charged and the cart is gone:

```text theme={null}
409
{"error":"The store's checkout timed out before the payment. Ask again for a fresh cart; nothing was charged.","code":"checkout_expired","conversation_id":"conv_..."}
```

```text theme={null}
409
{"error":"The store's checkout closed before the payment. Ask again for a fresh cart; nothing was charged.","code":"browser_session_lost","conversation_id":"conv_..."}
```

```text theme={null}
409
{"error":"I couldn't get back to duralexusa.com's payment step, so no card went in and nothing was pressed. Nothing was charged; ask again for a fresh cart.","code":"payment_step_lost","conversation_id":"conv_..."}
```

```text theme={null}
409
{"error":"The store did not place this order and charged nothing. Ask again for a fresh cart.","code":"not_placed","conversation_id":"conv_..."}
```

Send the shopper's request again to build a fresh cart.

A confirm that arrives while the store's checkout is still opening is refused:

```text theme={null}
409
{"error":"The store's checkout is still opening. Say yes again in a moment; nothing was charged.","code":"checkout_opening","conversation_id":"conv_..."}
```

Send the same confirm again in a few seconds.

A store total that moved after the shopper said yes stops the payment before Agentcard presses Pay:

```text theme={null}
409
{"error":"duralexusa.com's total is no longer the 28.36 USD you confirmed, so nothing was pressed. Nothing was charged; ask again for a fresh cart.","code":"total_changed","conversation_id":"conv_..."}
```

```text theme={null}
409
{"error":"duralexusa.com's total is above the ceiling you approved, so nothing was pressed. Nothing was charged.","code":"total_over_ceiling","conversation_id":"conv_..."}
```

Ask again for a fresh cart, and show the shopper its new total before they say yes.

A store whose payment form Agentcard cannot type a card into safely is refused before any card goes in:

```text theme={null}
409
{"error":"Agentcard can't hold shop.example.com's card request safely, so it typed no card. Nothing was charged.","code":"processor_not_recognised","conversation_id":"conv_..."}
```

Offer the shopper the same product at another store. The store list marks such a store with `supported_reason: "gate_refused"`, which means Agentcard cannot pay at its payment form, as [Check where Agentcard can pay](https://docs.agentcard.com/opencommerce/guides/checking-where-agentcard-can-pay.md) shows.

A store that cancels orders Agentcard places as a guest, without a store account, is refused:

```text theme={null}
409
{"error":"shop.example.com cancels orders placed this way, so I won't place one there. Nothing was ordered or charged. Want it from another store?","code":"store_cancels_guest_orders","conversation_id":"conv_..."}
```

Offer the shopper another store.

A payment Agentcard cannot confirm either way is refused, and it may have gone through:

```text theme={null}
409
{"error":"That payment may have gone through: the store had not confirmed the order when the check ended. Agentcard is reconciling it, so check your card and the store before buying again.","code":"charge_unresolved","conversation_id":"conv_..."}
```

Do not buy the same product again. Tell the shopper Agentcard is checking with the store, and wait for the message that reports the order.

A live account that cannot pay at a store's own checkout yet is refused:

```text theme={null}
409
{"error":"Browser checkouts place no live orders yet for this account. Nothing was charged.","code":"browser_live_disabled","conversation_id":"conv_..."}
```

Contact Agentcard to turn on live orders at stores' own checkouts.

## Pay with Stripe Link

A shopper can pay with their Stripe Link wallet, as [Pay with Stripe Link](https://docs.agentcard.com/purchase-api/link-seal.md) shows. A Link confirm missing a field is refused:

```text theme={null}
400
{"error":"link_payment_invalid","code":"link_payment_invalid","message":"A confirm under payment_source \"link\" sends link_payment with the approved spend request's spend_request_id, amount_cents and currency. Nothing was charged."}
```

Send `conversation_id`, and `link_payment` with its `spend_request_id`, `amount_cents` and `currency`.

A cart Link cannot pay is refused:

```text theme={null}
409
{"error":"link_payment_unavailable","code":"link_payment_unavailable","message":"This cart can't be paid with Stripe Link yet. Nothing was charged. Keep the cart; the shopper can pay another way."}
```

Cancel the Link payment, and offer the Vault for that cart. Link pays nothing in the sandbox, so every Link confirm there answers this.

A Link payment smaller than the store's total, or in another currency, is refused:

```text theme={null}
409
{"error":"link_amount_short","code":"link_amount_short","message":"The Stripe Link payment the shopper approved is less than the store's total, or in another currency. Nothing was charged. Ask the shopper to approve the cart's total in Stripe Link, then confirm again."}
```

Ask the shopper to approve the cart's total in Link, then confirm again.

A checkout that had to start again at a new total is refused:

```text theme={null}
409
{"error":"The store's checkout had to start again, and it came to a different total than the one the shopper confirmed, so Stripe Link paid nothing. Nothing was charged. Ask again for a fresh cart and show the shopper its total before they pay.","code":"cart_total_changed","charge_status":"none","conversation_id":"conv_..."}
```

Ask again for a fresh cart, and show the shopper its total.

After a Link confirm, your server sends the shopper's Link approval, encrypted, to Agentcard, as [the Link encryption guide](https://docs.agentcard.com/purchase-api/link-seal.md) shows. That call has four refusals:

```text theme={null}
404
{"error":"No Stripe Link approval with this id waits for this shopper and app.","code":"link_seal_not_found"}
```

Post to the `approval_id` the confirm returned, with the same shopper's `external_user_id`.

```text theme={null}
409
{"error":"This Stripe Link approval was already sealed, or its payment ended.","code":"link_seal_answered"}
```

Read the conversation to learn how the order went.

```text theme={null}
410
{"error":"This Stripe Link approval stopped waiting for its seal. Nothing was charged; confirm the cart again.","code":"link_seal_expired"}
```

Confirm the cart again, and send the encrypted approval before the `seal_by` deadline the new confirm returns.

```text theme={null}
400
{"error":"The seal is not a Stripe Link grant sealed to this approval's key.","code":"link_seal_invalid"}
```

Encrypt the approval again with the key whose id the confirm returned as `key_id`.

## Bring back a saved cart

A call that names a saved cart can be refused three ways:

```text theme={null}
404
{"error":"Saved carts are not available for this app yet.","code":"carts_not_available"}
```

```text theme={null}
404
{"error":"cart_id not found","code":"cart_not_found"}
```

```text theme={null}
409
{"error":"This cart has ended and cannot be reopened.","code":"cart_ended"}
```

Leave out the saved cart and send the shopper's request again to start a new cart.

## Find an order

A read of one placed order names it by `order_id`. An `order_id` that is not this shopper's is refused:

```text theme={null}
404
{"error":"order_id not found","code":"order_not_found"}
```

Send the `order_id` the `order.placed` event carried, with the same shopper's id.

An order number two stores share is refused with both stores:

```text theme={null}
409
{"error":"More than one order carries this order_id. Ask again with ?merchant= to say which one.","code":"order_id_ambiguous","merchants":["retail","doordash"]}
```

Send the same read again with `merchant` set to one of the listed stores.

## Retry when Agentcard is busy

Agentcard answers one call at a time in each conversation. A call sent while the last one is still running waits, then is refused:

```text theme={null}
409
{"error":"A turn is already running on this conversation. Wait for it to finish (GET /buy/conversations/:id reports turn_in_progress), then send the next ask or confirm.","code":"turn_in_progress","conversation_id":"conv_..."}
```

Wait for the last call's answer, or read the conversation until `turn_in_progress` is `false`, then send the call again.

A short outage is refused, and nothing ran:

```text theme={null}
503
{"error":"Purchasing is briefly unavailable. Retry in a few seconds.","code":"turn_lock_unavailable","conversation_id":"conv_..."}
```

```text theme={null}
502
{"error":"The shopping agent could not complete this turn.","code":"turn_failed","conversation_id":"conv_...","request_id":"req_..."}
```

Send the same call again after a few seconds. Give Agentcard the `request_id` if it keeps failing.

## Read a declined answer

A purchase Agentcard tried and could not finish answers with `status: "declined"` and a `decline_code`. `reply` explains it to the shopper. A sandbox confirm declines this way on purpose:

```json theme={null}
{
  "conversation_id": "conv_ddaaf96c052893b13209e6c9",
  "status": "declined",
  "reply": "I couldn't place the order. This connection is in test mode, and test mode can't pay a real store like Amazon. Nothing was charged. ...",
  "decline_code": "sandbox_mode",
  "charge_status": "none",
  "cart": { "hash": "55952914e74b3539", "totalCents": 1112, ... }
}
```

| `decline_code` | What it means | What to do next |
| - | - | - |
| `sandbox_mode` | A sandbox purchase stopped at payment, as it always does. | Nothing. Use live credentials to place orders. |
| `vault_approval_required` | The shopper has to approve the payment. Not a failure. | Send the shopper the approval link. Agentcard finishes the checkout once they approve. |
| `vault_unavailable` | The shopper has no card saved in the Vault. | Send the shopper the add-a-card link, then confirm again. |

Other values name the store's own reason, such as a sold-out item. Show the shopper `reply`, and send their answer as the next message.

> [tab] SDK
>
> The buy tool reads two of these for you. `vault_approval_required` arrives as `status: 'approval_sent'`, and the approval link goes to `sendLink`. A shopper with no card arrives as `status: 'needs_card'`, with the add-a-card link.

> [tab] MCP
>
> The `buy` tool reads two of these for you. `vault_approval_required` arrives as `status: "approval_sent"`, with an `approval` link in `links`. A shopper with no card arrives as `status: "needs_card"`, with an `add_card` link.

> [tab] API
>
> The approval link is `approval_url`, and the add-a-card link is `add_card_url`. `charge_status` says whether money moved: `none` when nothing was charged, `settled` when the store charged the card, and `unknown` when the store took the card and stopped without confirming. `reply` already tells the shopper which, so show it as it is.


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