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

# Message types

> The message Agentcard sends for each moment a shopper should hear about, and the helpers that tie a message to the link it ends.

A `ShopperMessage` is one moment of a purchase that a shopper should hear about, read from an Agentcard event and ready to post into that shopper's chat. `agentcard.listen` and `agentcardWebhook` hand your `onMessage` one for each such event, together with your own id for the shopper.

```ts messages.ts theme={null}
import { AgentcardClient } from '@agent-cards/commerce-sdk';

const agentcard = new AgentcardClient({
  clientId: process.env.AGENTCARD_CLIENT_ID ?? '',
  clientSecret: process.env.AGENTCARD_CLIENT_SECRET ?? '',
});

agentcard.listen({
  onMessage: (shopperId, message) => {
    if (message.kind === 'order_placed') recordOrder(shopperId, message.facts.orderId);
    return postToChat(shopperId, message.text);
  },
});
```

`recordOrder` and `postToChat` stand for your own code. The listener records each placed order and posts each message's `text` into the right chat. Give a `switch` over `kind` a default branch that sends `text`, because Agentcard can add a kind later.

## ShopperMessage

| Field | Type | Description |
| - | - | - |
| `eventId` | `string` | The event id. Agentcard delivers at least once: handle each id once. |
| `type` | `'purchase.message'`, `'order.confirmed'` or `'order.updated'` | The event type the message arrived as. |
| `kind` | `string` | The moment the message is about. See [Kinds](#kinds). |
| `userId` | `string` | The shopper's Agentcard user id. |
| `externalUserId` | `string` or `null` | Your own id for the shopper, when you gave Agentcard one: the chat to post `text` into. |
| `conversationId` | `string` or `null` | The buy conversation the event belongs to, when Agentcard names one. |
| `threadId` | `string` or `null` | Your own id for the chat the message's purchase belongs to, when the tool was built with `threadId`: the chat to post `text` into. `null` for a purchase opened without a thread, and for a message about the shopper alone. |
| `text` | `string` | Ready to send to the shopper as is. Agentcard writes it for a `purchase.message`, and the package writes it for `order_confirmed` and `order_updated`. |
| `note` | `string` | For your agent: the facts of what happened, marked as written by the system and not typed by the shopper. Empty when the message carries no note. |
| `facts` | `ShopperFacts` | The same values one by one, for a company that writes its own copy. |
| `advances` | `boolean` | `true` when the message ends a step the shopper took outside the chat. See [`buy.nextStep`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#next-step). |
| `clientId` | `string` or `null` | The OAuth client id of the app the shopper connected through, when the event names it. |
| `livemode` | `boolean` | `false` for a sandbox event. |
| `created` | `number` | Unix seconds. |

A message about the shopper alone, such as a saved card, has both `threadId` and `conversationId` set to `null` and belongs to every chat.

Send `text` when you have no agent, and for every message that carries a link, so the link arrives exactly as Agentcard wrote it. Hand `note` to your agent as a turn when you want the agent to say it in its own voice. When a message has no `note`, or your agent cannot run the turn, send `text`.

## Kinds

`kind` is one of the values below. The last two columns say whether the message sets `advances`, and which link it ends.

| `kind` | When it arrives | `advances` | Ends |
| - | - | - | - |
| `order_placed` | The shopper approved, and Agentcard placed the order. | `false` | `approval`, `completed` |
| `order_failed` | The order failed after the shopper approved. | `false` | `approval`, `completed` |
| `order_not_placed_yet` | The shopper approved, and the order is not placed yet. | `false` | `approval`, `completed` |
| `order_unconfirmed` | The store's reply to the order was lost, so the order may exist, and Agentcard is confirming it. | `false` | `approval`, `completed` |
| `bank_challenge` | The shopper's bank asked them to approve the payment, in their banking app or with a code. `facts.validUntil` is when Agentcard stops waiting. | `false` | `approval`, `completed` |
| `approval_expiring` | The approval link expires soon. `text` carries the link. | `false` | None |
| `approval_expired` | The approval expired before the shopper answered, and no charge went through. | `false` | `approval`, `expired` |
| `approval_declined` | The shopper declined the approval, and no charge went through. | `true` | `approval`, `declined` |
| `payment_declined` | The shopper approved, and the payment was refused before the order went in. `facts.reason` says why. | `false` | `approval`, `completed` |
| `card_link_unfinished` | The shopper has not added a card from their card link. `text` carries the link again. | `false` | None |
| `card_link_expired` | The card link expired before the shopper added a card. | `false` | `vault`, `expired` |
| `cart_idle` | A cart sat, and nobody sent it for approval. `facts.nudgeNumber` counts the nudges. | `false` | None |
| `card_added` | The shopper saved a card from the card link your app sent, or picked one they keep. | `true` | `vault`, `completed` |
| `store_connected` | The shopper signed in to their own account at the store from the sign-in link your app sent. | `true` | `store_login`, `completed` |
| `store_connect_failed` | The shopper's sign-in to the store did not go through, and the link no longer works. `text` offers a new one. | `false` | `store_login`, `failed` |
| `store_connect_expired` | The sign-in link expired before the shopper finished signing in. `text` offers a new one. | `false` | `store_login`, `expired` |
| `cart_ready` | The store's checkout built the cart an answer named as still being built. `text` gives the store's own total, and nothing is paid until the shopper says yes to it. | `false` | None |
| `cart_needs_input` | That checkout asks the shopper something first, such as a size, a delivery address, a sign-in to the store or an approval of the most the order can cost. | `false` | None |
| `cart_failed` | That checkout built no cart, and nothing was ordered or charged. | `false` | None |
| `order_confirmed` | The retailer accepted the order on its side, with its own order number and delivery window. | `false` | `approval`, `completed` |
| `order_updated` | The order reached a new delivery stage, named in `facts.orderStatus`. | `false` | None |

The first eighteen kinds arrive as `purchase.message` events. `order_confirmed` arrives as `order.confirmed`, and `order_updated` arrives as `order.updated`. A message whose `kind` is `approval_expiring` or `card_link_unfinished` leaves its link open.

## ShopperFacts

The values of a message one by one. A fact that does not apply to the message is absent.

| Field | Type | Description |
| - | - | - |
| `merchantName` | `string`, optional | The store's name. |
| `totalCents` | `number`, optional | The total in the currency's smallest unit: `2306` is `\$23.06`. |
| `currency` | `string`, optional | The three-letter currency code. |
| `cardBrand` | `string`, optional | The brand of the card. |
| `cardLast4` | `string`, optional | The last four digits of the card. |
| `orderId` | `string`, optional | Agentcard's order id. |
| `reason` | `string`, optional | Why an order failed or was not placed, or a payment was declined, in words. |
| `approvalUrl` | `string`, optional | The approval link. |
| `approvalExpiresAt` | `string`, optional | When the approval link stops working, as an ISO 8601 timestamp. |
| `cardLinkUrl` | `string`, optional | The card link. |
| `retryUntil` | `string`, optional | Until when Agentcard retries the order, as an ISO 8601 timestamp. |
| `validUntil` | `string`, optional | When the message stops holding, as an ISO 8601 timestamp: the expiry of any link or window its text names. A message that stays true carries none. |
| `nudgeNumber` | `number`, optional | `1` for a cart's first nudge, `2` for its second. |
| `retailerOrderId` | `string`, optional | The retailer's own order number. |
| `deliveryWindow` | `string`, optional | The retailer's quoted delivery window, in its own words. |
| `orderStatus` | `OrderStatus`, optional | The order's delivery stage. |
| `previousOrderStatus` | `OrderStatus`, optional | The stage before this one. |
| `statusTitle` | `string`, optional | The store's own line for the stage, such as "Your Dasher is nearby". |
| `arrivalEarliest` | `string`, optional | The earliest arrival the store estimates, as an ISO 8601 timestamp. |
| `arrivalLatest` | `string`, optional | The latest arrival the store estimates, as an ISO 8601 timestamp. |
| `deliveredAt` | `string`, optional | When the order was delivered, as an ISO 8601 timestamp. |
| `canceledReason` | `string`, optional | Why the store canceled the order, in its own word. |
| `linkPayment` | `LinkPaymentFacts`, optional | On a purchase the shopper paid with Link: `spendRequestId`, the Link payment, and `charge`, whether the store charged it. See [LinkPaymentFacts](#linkpaymentfacts). |

A message is stale once `validUntil` has passed. Drop a stale message instead of sending it. `isStale(message)` checks it, and `listen` and `agentcardWebhook` do so for you.

### LinkPaymentFacts

`charge` says how a purchase paid with Link ended at the store:

| `charge` | What it means |
| - | - |
| `placed` | The store took the order. |
| `none` | The store's checkout did not take Link's card, so nothing was charged. |
| `maybe` | The store has not answered yet, and Agentcard is checking with it. |

`buy.walletOutcome(message)` reads it for you: on `none` it cancels the Link payment at once, and it answers the line to post in place of `text`. See [Read how a Link payment ended](https://docs.agentcard.com/commerce-sdk/guides/paying-with-a-link-wallet.md#read-how-a-link-payment-ended).

### OrderStatus

`orderStatus` is one of `confirmed`, `courier_assigned`, `courier_at_store`, `ready_for_pickup`, `picked_up`, `arriving`, `delivered` or `canceled`. A stage Agentcard adds later reads as its own name.

## Event types and next-step kinds

| Constant | Value | Description |
| - | - | - |
| `SHOPPER_EVENT_TYPES` | `purchase.message`, `order.confirmed`, `order.updated` | The event types that carry a message for a shopper. Subscribe a webhook endpoint to each by name. |
| `NEXT_STEP_KINDS` | `card_added`, `store_connected`, `approval_declined` | The kinds after which your agent takes the next step on its own. Every other kind's `text` is the whole message: post it as is. |

## Action link helpers

A `vault`, `store_login` or `approval` link is a step the shopper takes outside the chat. Each step ends with a shopper message, and these helpers say which message ends which link.

| Export | Description |
| - | - |
| `ACTION_LINK_KINDS` | `['vault', 'store_login', 'approval']`. |
| `ACTION_LINK_ENDINGS` | For each kind of step, the message kinds that end it and how. The `Ends` column of [Kinds](#kinds) shows the same table. |
| `actionLinkId(link)` | Returns a stable id for a link, such as `vault_1x9k2qd`. The id is the same each time the same link is handed over, on the server and in the browser, and holds no part of the URL. |
| `actionLinkOutcome(link, message)` | Returns how `message` ends the step `link` is, or `null` when it leaves the step open. |
| `isActionLink(link)` | Returns `true` for a `vault`, `store_login` or `approval` link that has a page to open. Returns `false` for a link `actionLinkRefusal` refuses. |
| `actionLinkRefusal(link)` | Returns why a step's link never opens, `not_https` or `host_not_allowed`, or `null` when it may open. |
| `ACTION_LINK_HOSTS` | The hosts each kind of step opens on. A `store_login` link opens only on `agentcard.sh`, `agentcard.com` and their subdomains. |
| `ActionLinkRefusedError` | The error `open` throws for a link it refuses, carrying the link's `kind` and the `reason`. |

A `vault` or `approval` link opens on any `https:` host, since a company's own Vault domain carries them too.

`actionLinkOutcome` returns one of `completed`, `declined`, `failed` or `expired`. An approval is `completed` once the shopper approved, even when the order then failed or the payment was refused, because the approval page has nothing more to do.

The function returns `null` for a reminder such as `card_link_unfinished` or `approval_expiring`. `actionLinkOutcome` also returns `null` when the message's facts name another link of the same kind (`facts.approvalUrl` or `facts.cardLinkUrl`), or another store: a link that names its `store` stays open when `facts.merchantName` names a different one.

## Action windows

`actionWindows` comes from `@agent-cards/commerce-sdk/browser`. The function opens each step in a pop-up window centered over the chat, so the shopper never leaves it, and closes the pop-up the moment the message that ends the step arrives. A phone's browser opens the pop-up as a tab, and `settle` closes that tab the same way.

```ts chat.ts theme={null}
import { actionWindows } from '@agent-cards/commerce-sdk/browser';

const windows = actionWindows({
  onEnded: (step, outcome) => markStepDone(step.id, outcome),
  onClosed: (step) => keepOfferingStep(step.id),
});

// The link's own click handler, so the browser counts the tap as the reason for the pop-up.
// For a link `open` refuses, it throws, and the handler cancels the tap so the link never opens.
stepLink.addEventListener('click', (event) => {
  try {
    if (windows.open(link)) event.preventDefault();
  } catch (error) {
    event.preventDefault();
    console.error(error);
  }
});

// Each shopper message your server forwards from listen or the webhook, with its kind and facts.
onShopperMessage((message) => windows.settle(message));
```

`markStepDone`, `keepOfferingStep`, `stepLink`, `link` and `onShopperMessage` stand for your own code. When the browser blocks the pop-up, `open` returns `null` and the link opens the way it would have, as a new tab.

### Options

```ts theme={null}
actionWindows(options?: ActionWindowsOptions): ActionWindows
```

| Option | Type | Description |
| - | - | - |
| `window` | `WindowLike`, optional | The page's window. Default: `globalThis.window`. Pass one to test with a fake. |
| `width` | `number`, optional | The pop-up's width in CSS pixels, kept inside the screen. Default `480`. |
| `height` | `number`, optional | The pop-up's height in CSS pixels, kept inside the screen. Default `760`. |
| `pollMs` | `number`, optional | How often to check whether the shopper closed a pop-up, in milliseconds. Default `500`. |
| `onEnded` | `(step: ActionWindow, outcome: ActionLinkOutcome) => void`, optional | Hears a step that ended while its pop-up was open, after `settle` closed the pop-up. Show the step as done here. |
| `onClosed` | `(step: ActionWindow) => void`, optional | Hears a pop-up the shopper closed before the step ended. The step is still open: keep offering its link. |

### Methods

| Method | Returns | Description |
| - | - | - |
| `open(link)` | `ActionWindow` or `null` | Opens the step's page in a pop-up, or brings its pop-up to the front when one is open already. Returns `null` when the link is not a step with a page or the browser blocked the pop-up, and throws `ActionLinkRefusedError` for a link it refuses. |
| `settle(message)` | `Array<{ step, outcome }>` | Closes each open pop-up whose step the message ends, and calls `onEnded` for each. Returns the steps it ended, or an empty list. |
| `get(link)` | `ActionWindow` or `null` | Returns the open pop-up for the link, or `null`. |
| `dispose()` | `void` | Stops watching every pop-up and leaves each one open, so a chat that remounts never shuts the page a shopper is typing a card into. |

Call `open` from the tap's click handler. `ActionWindow` has `id` (the link's `actionLinkId`), `kind`, `url`, `store` (`string` or `null`) and `open` (`false` once the window closed). `open` sets the pop-up's `opener` to `null` as it opens, before its page loads, so the step's page can neither move the chat's page nor post to it. The chat keeps the window itself, so `settle` still closes the pop-up and `onClosed` still hears the shopper close it.

A browser finds no pop-up with no opener by its name. After a chat remounts, a tap on a step whose pop-up is still open opens a second window, and the first stays open until the shopper closes it.

`open` refuses every `javascript:`, `data:`, `http:` and relative address, and an `https:` address with a user name before its host. `open` refuses a local stack's `http://localhost` links too, since the SDK has no development mode to allow them. The refusal throws `ActionLinkRefusedError` and opens nothing. `console.log` prints the following error, `kind` and `reason` for a Vault link on a local stack and for a store sign-in on another host:

```text theme={null}
ActionLinkRefusedError: A vault link was not opened: its page is not an https URL.
  kind: 'vault', reason: 'not_https'
ActionLinkRefusedError: A store_login link was not opened: its host is not one a store_login link opens.
  kind: 'store_login', reason: 'host_not_allowed'
```

| `reason` | What it means | What to do next |
| - | - | - |
| `not_https` | The link's page is not an absolute `https:` URL, or it names a user before its host. | Pass the link exactly as the buy tool or `AgentcardClient` handed it over. |
| `host_not_allowed` | A store sign-in link points outside `agentcard.sh`, `agentcard.com` and their subdomains. | Pass the link exactly as the buy tool or `AgentcardClient` handed it over. |

The buy tool never hands over a link `open` refuses, so a refusal means your code built or changed the link.


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