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

# Commerce SDK

> Give your agent one tool that buys for your shoppers at real stores, and post each purchase update into the shopper's chat.

The `@agent-cards/commerce-sdk` package gives your agent a `buy` tool that searches stores, builds a cart, and places the order once the shopper approves it. The package also hands your server a message, ready to post into the shopper's chat, for each moment the shopper should hear about, such as a saved card or a placed order.

## Install

```bash theme={null}
npm install @agent-cards/commerce-sdk
```

The package runs on Node 18 or later and has no dependencies. The browser entry `@agent-cards/commerce-sdk/browser` imports no Node module, so any build tool takes it.

## Wire it up

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

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

const buy = buyTool({ agentcard, externalUserId: 'user-42' });
const turn = buy.turn('two packs of AA batteries from Amazon');
```

The snippet builds one `AgentcardClient`, one `buy` tool for the shopper `user-42`, and one turn for the shopper's message. Pass `turn` to your model as its tool. The [Quickstart](https://docs.agentcard.com/commerce-sdk/quickstart.md) page walks through each framework.

## Exports

Every name below comes from `@agent-cards/commerce-sdk`, except the browser entry.

### Client

| Export | Kind | What it is |
| - | - | - |
| [`AgentcardClient`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client) | class | Holds your credentials and talks to Agentcard. |
| [`AgentcardApiError`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client#agentcardapierror) | class | The error every refusal and failed call throws. |
| [`DEFAULT_BASE_URL`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client#constants) | constant | `https://api.agentcard.sh`. |
| [`BUY_TURN_TIMEOUT_MS`](https://docs.agentcard.com/api-reference/commerce-sdk/agentcard-client#constants) | constant | The wait for one purchase turn, in milliseconds. |

### Buy tool

| Export | Kind | What it is |
| - | - | - |
| [`buyTool`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool) | function | Builds the buy tool for one shopper. |
| [`BUY_TOOL_NAME`, `BUY_TOOL_DESCRIPTION`, `buyToolDefinition`, `parseBuyToolInput`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#standalone-helpers) | values | The tool's name, description, definition and input check. |
| [`forModel`, `forModelError`, `replyAsWritten`, `stripLinks`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#standalone-helpers) | functions | Turn an answer or an error into what a model may read. |
| [`instantAck`, `instantReaction`, `ackFor`, `keepsYes`, `ACK_REACTION`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#standalone-helpers) | values | Decide whether a message gets a reaction or an instant reply. |
| [`toOpenRouterTool`, `toAnthropicTool`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#frameworks) | functions | Adapters for OpenRouter's agent SDK, and a deprecated pass-through. |
| [`productAction`](https://docs.agentcard.com/api-reference/commerce-sdk/buy-tool#buytoolproduct) | function | Names what taking a product does: `buy`, `reserve` or `book`. |

### Turn

| Export | Kind | What it is |
| - | - | - |
| [`buy.turn`](https://docs.agentcard.com/api-reference/commerce-sdk/turn) | method | Opens the turn of one shopper message. |
| [`buy.nextStep`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#next-step) | method | Opens the turn your agent takes once the shopper finishes a step outside the chat. |
| [`nextStepPrompt`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#next-step) | function | Writes the model's message for a next-step turn. |
| [`toMessages`, `messageStream`, `typingDelay`](https://docs.agentcard.com/api-reference/commerce-sdk/turn#message-helpers) | functions | Cut text into chat messages and space them. |

### Listen

| Export | Kind | What it is |
| - | - | - |
| [`agentcard.listen`, `listenToAgentcard`](https://docs.agentcard.com/api-reference/commerce-sdk/listen) | method, function | Hear every event over one connection your server opens. |
| [`AGENTCARD_EVENT_TYPES`](https://docs.agentcard.com/api-reference/commerce-sdk/listen#event-types) | constant | Every event type Agentcard sends your company. |

### Webhooks

| Export | Kind | What it is |
| - | - | - |
| [`agentcardWebhook`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler) | function | Builds the handler for your webhook endpoint. |
| [`purchaseAgentWebhook`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler#purchaseagentwebhook) | function | The earlier handler, for `purchase.message` events only. |
| [`verifyAgentcardWebhook`, `AgentcardSignatureError`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler#verify-a-delivery) | function, class | Check a delivery's signature. |
| [`readShopperMessage`, `readPurchaseMessage`, `isStale`](https://docs.agentcard.com/api-reference/commerce-sdk/webhook-handler#read-a-message) | functions | Read the message an event carries. |

### Messages and steps

| Export | Kind | What it is |
| - | - | - |
| [`ShopperMessage`, `ShopperFacts`, `ShopperMessageKind`](https://docs.agentcard.com/api-reference/commerce-sdk/messages) | types | The message you post into a shopper's chat. |
| [`SHOPPER_EVENT_TYPES`, `NEXT_STEP_KINDS`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#event-types-and-next-step-kinds) | constants | The event types that carry a message, and the kinds that advance a step. |
| [`ACTION_LINK_KINDS`, `ACTION_LINK_ENDINGS`, `actionLinkId`, `actionLinkOutcome`, `isActionLink`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#action-link-helpers) | values | Tell which message ends which link. |

### Browser entry

| Export | Kind | What it is |
| - | - | - |
| [`actionWindows`](https://docs.agentcard.com/api-reference/commerce-sdk/messages#action-windows) | function | Opens each step in a pop-up and closes it when the step ends. |

The browser entry also re-exports the action-link helpers.

## Guides

Each guide shows what the shopper sees, the code that implements it, and how to check it in the sandbox.

* [Quickstart](https://docs.agentcard.com/commerce-sdk/quickstart.md)
* [Showing products and carting the one the shopper picks](https://docs.agentcard.com/commerce-sdk/guides/showing-products.md)
* [Showing stores and their menus](https://docs.agentcard.com/commerce-sdk/guides/showing-stores-and-menus.md)
* [Sending each link: approval, Vault and store sign-in](https://docs.agentcard.com/commerce-sdk/guides/sending-each-link.md)
* [Adding a card for a new shopper](https://docs.agentcard.com/commerce-sdk/guides/adding-a-card.md)
* [Approving a purchase](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md)
* [Signing in to a store's account](https://docs.agentcard.com/commerce-sdk/guides/signing-in-to-a-store.md)
* [Taking the next step once the shopper finishes outside the chat](https://docs.agentcard.com/commerce-sdk/guides/taking-the-next-step.md)
* [Showing the cart](https://docs.agentcard.com/commerce-sdk/guides/showing-the-cart.md)
* [Answering each shopper message in its own turn](https://docs.agentcard.com/commerce-sdk/guides/answering-each-message.md)
* [Acknowledging the shopper: a reaction or a short text](https://docs.agentcard.com/commerce-sdk/guides/acknowledging-the-shopper.md)


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