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

# Approving a purchase

> Ask for the shopper's yes, send the approval link, and let Agentcard place the order the moment they approve.

The shopper reads the cart and says yes. Your agent sends an approval link, and the shopper approves the payment on their phone with a passkey, which is Face ID or Touch ID on an iPhone. Agentcard places the order the moment they approve, and the chat reads "order placed" with nothing else to type.

Two steps are the shopper's own: the yes to the cart, and the approval. Your code never approves for them, and the model never places an order without the yes.

The steps below cover the Vault's approval. To let a shopper approve in their own Link wallet instead, see [Paying with a Stripe Link wallet](https://docs.agentcard.com/commerce-sdk/guides/paying-with-a-link-wallet.md).

## Confirm the cart

The model sets `confirm` to true only when the shopper said yes to the cart in the model's last result, asks to check out or pay, says they added the card for a cart that waits, says they approved, or asks for the approval link again. The tool then confirms the cart Agentcard last showed, so you handle no cart hash and no conversation id.

Show the shopper the cart before the model confirms it. "Showing the cart" renders it.

When the confirm needs the shopper to approve, the answer carries these fields:

| Field | Value |
| - | - |
| `status` | `approval_sent` |
| `next_action` | `approve` |
| `links` | One `approval` link, handed to `sendLink` before the call returns. |
| `approval_expires_at` | When the approval link stops working, as an ISO 8601 timestamp. |

The approval link works for about 15 minutes. The model asks the shopper for one thing, the approval, in one short line, such as "approve the payment to place your order (up to \$19.02)". The dollar amount in the parentheses is the cart's `max_charge`, the most the shopper's card can be held for. A store that prices its final total at checkout asks for more than the cart's `total`, and a flight asks for exactly its total.

```ts chat.ts theme={null}
const turn = buyFor(shopper.id).turn(message, {
  sendLink: (link) => {
    if (link.kind === 'approval') return sendStep(shopper.id, 'Approve the payment', link); // your code
    return deliverLink(shopper.id, link);
  },
  onResult: (result) => {
    // result.carts holds each cart's total and the most it can be held for: approvedCeilingCents
    showCart(shopper.id, result.carts, result.next_action); // your code
  },
});
```

Show the cart's `approvedCeilingCents` beside its total whenever the cart carries one. A shopper who sees only the total approves less than the card can be held for.

## Place the order

The shopper taps the link, sees the store and the amount, and approves with their passkey. Agentcard places the order against that approval. Your server hears about it as a `purchase.message`, and the SDK hands you `text` ready to post:

| `kind` | When it arrives |
| - | - |
| `order_placed` | The shopper approved, and Agentcard placed the order. |
| `order_not_placed_yet` | The shopper approved, and the order is not placed yet. |
| `order_unconfirmed` | The store's reply to the order was lost, so the order may exist, and Agentcard is confirming it. |
| `bank_challenge` | The shopper's bank asked them to approve the payment. `text` says what to do. |
| `order_confirmed` | The retailer accepted the order on its side, with its own order number and delivery window. |
| `order_failed` | The order failed after the shopper approved. |

An order takes a few seconds to go through after the approval. A call that lands while Agentcard is still placing the order pauses once for 12 seconds and reads the conversation. The model then reads `order_placed` with the order number, or `placing`. A `placing` status means the order is going through, so the model never asks for another approval. A call that finds the order already placed reads it at once.

When `shopper_need_not_reply` is true, a `purchase.message` will tell the shopper how the order went, and the model tells them they need not reply. Post that message into the chat when it arrives. The order events your company receives are documented in [Order events](https://docs.agentcard.com/webhooks/orders/overview.md).

## Read where an order is

Ask Agentcard where an order is at any time, with the order number from the `order_placed` message, `message.order.orderId`:

```ts orders.ts theme={null}
const order = await agentcard.order('9632435a-4d4d-48bb-869d-5d0e3bd1410b', { externalUserId: shopper.id });
// a DoorDash order: order.status reads 'arriving', and order.estimated_arrival.latest is the latest arrival Agentcard knows
```

The call is `GET /buy/orders/{order_id}`, with `opts.merchant` sent as `?merchant=`. Agentcard answers from what it last read from the store, so the call returns at once and never calls the store. `status` is the stage the order has reached: `placed`, `confirmed`, `courier_assigned`, `courier_at_store`, `ready_for_pickup`, `picked_up`, `arriving`, `delivered` or `canceled`. `tracking` says whether Agentcard still follows the order, and `checked_at` says when it last asked the store.

| Merchant | `status` | `tracking` |
| - | - | - |
| DoorDash | Any stage. Agentcard reads the order about once a minute, for up to six hours after it was placed. | `live` while Agentcard follows the order, `ended` once it was delivered, canceled or six hours passed. |
| Retail, such as Amazon and Walmart | `placed`, `confirmed` once the store accepted the order, `picked_up` once its packages have tracking numbers, `arriving` once they are out for delivery, `delivered`, or `canceled` when the store canceled it. Agentcard reads the order about every 45 minutes, for up to 21 days after it was placed. | `live` while Agentcard follows the order, `ended` once it was delivered, canceled or 21 days passed. |

The answer also carries what the order holds, what it was sent with and where its packages are:

| Field | What it carries |
| - | - |
| `line_items` | The products the order holds, one entry per cart line, as the cart was when Agentcard placed it: `product_id`, `name`, `quantity`, `line_total_cents`, `currency`, `variant`, `options` and `url`. An empty list for an order placed before Agentcard kept its lines. |
| `shipping_address` | The address the order was placed to ship or deliver to: `name`, `line1`, `line2`, `city`, `state`, `postal_code`, `country` (ISO 3166-1 alpha-2) and `phone`, the phone your app sent with the address, if any. `null` for a pickup, an order that goes to no address, and an order placed before Agentcard kept the address. |
| `retailer_order_id` | The store's own order number, once the store names it. `null` at a store with none, such as DoorDash. |
| `delivery_window` | The delivery window the store quoted, in its own words, such as `Sat, Sep 6 - Tue, Sep 9`. |
| `shipments` | One entry per package with a tracking number: `carrier`, `tracking_number`, `tracking_url`, `status` (the carrier's word, such as `in_transit`) and `estimated_delivery` (a date such as `2026-09-08`). Empty until the first package ships, and at a store that delivers the order itself. |

A split retail order lists every package, and reads as far along as its slowest one.

### Decide how often to read

Let order events tell you when an order changes, and read the order only to fill a screen, such as the first time a shopper opens their order:

* DoorDash. Each stage arrives as [`order.updated`](https://docs.agentcard.com/webhooks/orders/order-updated) the minute Agentcard reads it. If you read the order yourself, read it no more than once a minute: Agentcard refreshes it about once a minute, so a faster read returns the same answer.
* Retail. Each stage arrives as `order.updated` with the order's `shipments`, and a cancellation by the store arrives as `order.updated` with `status: "canceled"`. [`order.confirmed`](https://docs.agentcard.com/webhooks/orders/order-confirmed) carries the store's order number and delivery window. Agentcard reads a retail order about every 45 minutes, so reading it more often returns nothing new. `checked_at` shows when Agentcard last read it.

Agentcard places a retail order from its own purchasing account, so the store's confirmation and shipping emails never reach the shopper. Show the shopper the receipt from `order.placed` and `order.confirmed`, and the carrier's tracking link from `shipments`. See [Order events](https://docs.agentcard.com/webhooks/orders/overview.md#build-the-receipt-from-order-events).

### Pick between two orders with one number

Two stores can give the same order number. Agentcard then refuses the read, and `error.body.merchants` lists the stores:

```text theme={null}
AgentcardApiError: More than one order carries this order_id. Ask again with ?merchant= to say which one.
```

Ask again with one of the stores `error.body.merchants` named:

```ts orders.ts theme={null}
const order = await agentcard.order('1001', { externalUserId: shopper.id }, { merchant: 'doordash' });
```

Agentcard refuses an order number it does not hold for that shopper:

```text theme={null}
AgentcardApiError: order_id not found
```

| `code` | `status` | What it means | What to do next |
| - | - | - | - |
| `order_id_ambiguous` | `409` | Two of the shopper's orders carry this order number. `error.body.merchants` names the stores. | Read again with `{ merchant: 'doordash' }`, naming one of the stores in `error.body.merchants`. |
| `order_not_found` | `404` | Agentcard holds no order with this number for that shopper. | Read the number from the `order_placed` message's `message.order.orderId`. |

## Let the shopper's rule pay

When the shopper's auto-approval rule, or your app's permission from [Enable auto-approval](https://docs.agentcard.com/vault/app-auto-approval.md), pays for the order, the confirm answers `placing` with no approval link. Agentcard pays this way only when all of these are true:

* The store's processor fixes the amount: the checkout confirms a Stripe PaymentIntent with the card inside, whose amount Agentcard reads from Stripe, or its card request names the total the shopper confirmed, as Paysafe's single-use payment handle does.
* The checkout page is on the store whose cart the shopper said yes to.
* The amount is within the rule's limits, or within your app's permission.

The model reads `placing` and `reply`, tells the shopper their rule is paying, and never asks for an approval. `reply` reads:

```text theme={null}
Your auto-approval rule is paying for this order at woolzies.com, so there is nothing to approve. Confirm again in a few seconds for the result.
```

Agentcard sends no `purchase.message` for an order the rule pays. The model's next call reads `order_placed` with the order number, or `placing` while the order is still going through.

When the shopper's bank asks to check the payment, the rule can't answer that check, so the order doesn't go through and nothing is charged. The confirm answers `declined` with `decline_code: bank_check_required`, and `reply` reads:

```text theme={null}
Your bank asked to check this payment at woolzies.com, and your auto-approval rule can't answer that check, so the order hasn't gone through. Nothing was charged.
```

| `decline_code` | What it means |
| - | - |
| `bank_check_required` | The shopper's bank asked to check the payment, which the rule can't answer, so the order didn't go through and nothing was charged. Post `reply` as it is. |

Agentcard won't start a second payment for the same item at that store until it resolves this one. The shopper can buy another item, or the same item at another store, in the meantime.

Every other purchase sends the approval link, including one at a Shopify store. A store that turns the card into a token charges that token later for whatever its order says, so no rule's limit can hold against the charge.

## Wait for the bank's approval

When the shopper's bank asks them to approve a payment in their banking app, post Agentcard's `reply` and wait. A payment the shopper approved with the approval link at a store's own checkout page reaches the bank's check, and Agentcard keeps that checkout open for 15 minutes while the shopper approves. When the shopper's auto-approval rule pays, a bank's check ends the purchase with `bank_check_required` instead, as [Let the shopper's rule pay](#let-the-shoppers-rule-pay) says.

Until the bank answers, a confirm of the same cart answers `needs_input`, with `next_action: "bank_challenge"` and `decline_code: "bank_challenge_required"`:

```json theme={null}
{
  "status": "needs_input",
  "next_action": "bank_challenge",
  "decline_code": "bank_challenge_required",
  "charge_status": "confirming",
  "reply": "Your bank asked you to confirm this $42.10 payment at shop.example. Open your bank's app and approve it there. Nothing is charged until your bank confirms.",
  "bank_challenge": {
    "kind": "app",
    "store": "shop.example",
    "amount_cents": 4210,
    "currency": "usd",
    "expires_at": "2026-11-20T18:15:00.000Z",
    "url": null
  }
}
```

Post `reply` as it is, and don't ask for a new approval. A confirm of the same cart only reads where the payment stands, and Agentcard never charges twice. `url` is always `null` for now.

Your server gets a `bank_challenge` message with the same text, then `order_placed` or `order_failed` once the bank answers and the store confirms. Post either the message or the `reply` from the confirm, not both: they say the same thing.

The buy tool's answer carries the same two fields: `next_action` reads `bank_challenge`, and `bank_challenge` holds the details above.

`bank_challenge.kind` says what the bank asked for:

| `kind` | What the bank asked | What the confirm answers |
| - | - | - |
| `app` | Approve in the bank's app. | `bank_challenge_required`. The order goes through once the shopper approves. |
| `unknown` | Approve, in the app or by message. | `bank_challenge_required`, and `reply` names both. |
| `code` | Type a code the bank sent. | `bank_challenge_unsupported`. The checkout can't take the code, so Agentcard checks with the store whether the order went through and `reply` asks the shopper not to order it again yet. |

A confirm of the same cart after a `code` challenge answers:

```json theme={null}
{
  "status": "needs_input",
  "next_action": null,
  "decline_code": "bank_challenge_unsupported",
  "charge_status": "confirming",
  "reply": "Your bank sent you a code to confirm this $42.10 payment at shop.example, and this checkout can't take a bank's code yet. Don't share the code with anyone. We're checking with shop.example whether the order went through, so please don't order it again yet.",
  "bank_challenge": {
    "kind": "code",
    "store": "shop.example",
    "amount_cents": 4210,
    "currency": "usd",
    "expires_at": "2026-11-20T18:15:00.000Z",
    "url": null
  }
}
```

After a `code` challenge, your server gets `order_placed` or `order_failed` once the store answers.

## Handle a refusal where it happens

### The shopper declines or lets the approval expire

| `kind` | When it arrives |
| - | - |
| `approval_declined` | The shopper declined the approval, and no charge went through. |
| `approval_expired` | The approval expired before the shopper answered, and no charge went through. |
| `approval_expiring` | The approval link expires soon. `text` carries the link, so send `text` as it is and the link arrives exactly as written. |
| `payment_declined` | The payment was refused before the order went in, such as a declined card. `facts.reason` says why, and no charge went through. |

After a decline, the cart stays on the table. The shopper can say yes for a new approval link, or tell the agent what to change.

`approval_declined` has `advances` set to true. Open `buy.nextStep(message)` as "Taking the next step once the shopper finishes outside the chat" shows, and the agent offers the next step without waiting for the shopper.

Drop a message after its `facts.validUntil`: the link or window it names has closed. `isStale(message)` checks it, and `listen` and the webhook handler skip stale messages for you.

### The cart changed

A cart changes when its price or contents drift after the shopper saw it. Agentcard refuses the confirm, and 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. Nothing is charged.

The other refusals that still answer the shopper come back as `needs_input` with the reason in `reply` and the code in `error_code`:

| `error_code` | What it means |
| - | - |
| `nothing_to_confirm` | The shopper confirmed with no cart. The model asks what they want. |
| `conversation_closed` | The shopper confirmed on a closed conversation. The model asks what they want. |
| `cart_not_ready` | The store is still building the cart, so it has no total yet. Nothing was confirmed or charged. |
| `turn_in_progress` | Agentcard is still working on the shopper's last request. The tool asks the model to call again in a moment. |
| A code that starts with `delivery_address` | The delivery address changed since the cart was built. The model asks for the cart again. |

### A confirm that takes too long

A request that takes Agentcard more than 110 seconds comes back before its cart is ready. A confirm that takes that long returns the order it placed, sends the approval link it paused on, or reads `placing` while the order is still going through. A call that times out throws an `AgentcardApiError` with `code: timeout`. Whether the turn ran is then unknown, so read the conversation before you call again:

```ts recover.ts theme={null}
const conversation = await agentcard.conversation(conversationId, { externalUserId: shopper.id });
// conversation.orders lists the orders placed, and conversation.turn_in_progress says whether a turn still runs.
```

Call the tool again only once that read shows the turn did not finish, because a second call sends a second turn.

## Check it with live credentials

The sandbox stops before payment. A confirm there ends `declined`: a paid purchase answers `decline_code: sandbox_mode`, and a table booking answers `decline_code: sandbox_unavailable`. Both mean the sandbox worked, and everything before the confirm ran for real. The approval link, the passkey tap, and the placed order exist only with live credentials.

To check them end to end, switch to live credentials as the Quickstart describes, and buy one inexpensive item with your own card.

1. Ask for the item, pick a product, and say yes to the cart.
2. Check that the approval link arrives alone, with one short line that names the amount, and that the model's reply holds no link.
3. Approve with your passkey. Check that "order placed" arrives in the chat with nothing typed after the tap.
4. Ask for the item again, say yes, and decline the approval. Check that no charge appears and the cart is still there.


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