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

# Show stores and their menus

> Render a card for each store near the shopper, then the menu of the store they pick.

A food delivery order starts with a choice of store. The shopper asks for tacos, and Agentcard answers with the taco places near them that deliver. Your chat shows a card for each store, with its picture, its name and its delivery time. The shopper taps one, and the next cards are that store's menu.

## Render a card for each store

Send the shopper's words with the address to deliver to, such as `get me tacos delivered to 1 Market St, San Francisco, CA 94105`. The answer lists the stores its reply names, up to eight, in the order the reply names them.

Show each store as a card with its picture, its name, its delivery time and an Order here button. The reply already asks which store in one short line, so show it under the cards.

Agentcard lists stores only for an answer that offers the shopper a choice of stores. An answer that searched stores on its way to a menu, or one that shows a cart, lists none. A later answer that offers the stores again lists them again, so every store the reply names arrives with its card.

> [tab] SDK
>
> Each store reaches `sendLink` as a link of kind `store`:
>
> ```ts chat.ts theme={null}
> const turn = buyFor(shopper.id).turn(message, {
>   sendLink: (link) => {
>     if (link.kind === 'store') return sendStoreCard(shopper.id, link); // your code
>     if (link.kind === 'product') return sendProductCard(shopper.id, link); // the menu items
>     return deliverStepLink(shopper.id, link);
>   },
> });
> ```
>
> | Field | Type | What it holds |
> | - | - | - |
> | `title` | string | The store's name. |
> | `url` | string or null | The store's page at the merchant. |
> | `storeId` | string | Agentcard's id for the store. It holds no link. |
> | `etaMinutes` | number or null | The delivery estimate in minutes, or null when the store showed none. |
> | `imageUrl` | string or null | The picture the store's card shows at the merchant, or null when it shows none. |
>
> `result.stores` carries the same stores for your code, each with its `url` and `linkSent`. The model reads each store by its `store_id`, name and `eta_minutes`, never its page, and reads `store_links_sent`, the number of store cards the shopper holds. A store link that your `sendLink` throws on counts as not sent.

> [tab] MCP
>
> The `buy` tool's result lists the stores in `stores`, each with `store_id`, `name` and `url`.
>
> ```json theme={null}
> {
>   "tool": "buy",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "ask": "get me tacos delivered to 1 Market St, San Francisco, CA 94105",
>     "confirm": false,
>     "new_order": false,
>     "product_id": null,
>     "store_id": null
>   }
> }
> ```
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Delivering to 1 Market St, San Francisco, CA 94105. Here are taco spots nearby. Which one sounds good?",
>   "stores": [
>     { "store_id": "297451", "name": "El Tesoro Taqueria and Grill", "url": "https://www.doordash.com/store/297451/" },
>     { "store_id": "40401865", "name": "Suavecito Birria & Tacos", "url": "https://www.doordash.com/store/40401865/" }
>   ],
>   ...
> }
> ```
>
> The MCP result carries no store picture and no delivery time, so a card built from it shows the store's name and its page.

> [tab] API
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "external_user_id": "user-42",
>     "ask": "get me tacos delivered to 1 Market St, San Francisco, CA 94105"
>   }'
> ```
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "conversation_id": "conv_d8b4740ba88a1f0ed369a08d",
>   "reply": "Delivering to 1 Market St, San Francisco, CA 94105. Here are taco spots nearby. Which one sounds good?\n\n- El Tesoro Taqueria and Grill\n- Suavecito Birria & Tacos\n- Street Taco\n...",
>   "stores": {
>     "merchant": "doordash",
>     "merchant_name": "DoorDash",
>     "items": [
>       {
>         "id": "297451",
>         "name": "El Tesoro Taqueria and Grill",
>         "store_page_url": "https://www.doordash.com/store/297451/",
>         "eta_minutes": 32,
>         "image_url": "https://img.cdn4dd.com/..."
>       },
>       {
>         "id": "40401865",
>         "name": "Suavecito Birria & Tacos",
>         "store_page_url": "https://www.doordash.com/store/40401865/",
>         "eta_minutes": 28,
>         "image_url": "https://img.cdn4dd.com/..."
>       },
>       ...
>     ],
>     "as_of": "..."
>   }
> }
> ```
>
> | Field | What it holds |
> | - | - |
> | `merchant_name` | Where the stores deliver from, such as `DoorDash`. |
> | `items[].id` | Agentcard's id for the store. You send it back when the shopper picks the store. |
> | `items[].name` | The store's name. |
> | `items[].store_page_url` | The store's page at the merchant. |
> | `items[].eta_minutes` | The delivery estimate in minutes, or `null` when the store showed none. |
> | `items[].image_url` | The picture the store's card shows at the merchant, or `null` when it shows none. |
>
> `stores` is `null` unless the answer offers a choice of stores.

## Pick a store

When the shopper taps a card, send the store's id back with their words, such as `Order from Suavecito Birria & Tacos`. Agentcard selects exactly that store before it answers and runs no new store search, so the next answer is that store's menu.

The shopper can also pick in their own words, with no id. Agentcard reads the store's name, the name with `please`, and `order here` or `this place` as a pick of a store the last answer listed. An answer of only a place in the list, such as `the second one` or `2`, picks the store at that place. A dish beside the store's name is a search, not a pick: `order tacos from el farolito` searches for tacos.

> [tab] SDK
>
> When the shopper picks a store, the model passes that `store_id`. The Order here button can send the shopper's words alone, and the tool reads them as a pick, so a tap needs no id from your app. Your own code can pick too, with `buy.answer` and the link's `storeId`:
>
> ```ts store-button.ts theme={null}
> const result = await buyFor(shopper.id).answer({
>   ask: link.title ?? '',
>   confirm: false,
>   new_order: false,
>   store_id: link.storeId, // from the store link, never typed by the shopper
> });
> ```
>
> `result.store_pick` says what happened: the store's id and name, and `selected`, whether the merchant took the selection. When it did not, Agentcard selects the store while it writes its answer. The model reads the same `store_pick`.
>
> A pick starts no search, so it gets no instant reply. [Acknowledge the shopper](https://docs.agentcard.com/opencommerce/guides/acknowledging-the-shopper.md) shows how your chat can still react.

> [tab] MCP
>
> Call `buy` with the shopper's words and the store's `store_id`. Never send `store_id` together with `product_id`.
>
> ```json theme={null}
> {
>   "tool": "buy",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "ask": "Order from Suavecito Birria & Tacos",
>     "confirm": false,
>     "new_order": false,
>     "product_id": null,
>     "store_id": "40401865"
>   }
> }
> ```

> [tab] API
>
> Send the store's `id` as `pick.store_id`, with the shopper's words as `ask`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "conversation_id": "conv_d8b4740ba88a1f0ed369a08d",
>     "external_user_id": "user-42",
>     "ask": "Order from Suavecito Birria & Tacos",
>     "pick": { "store_id": "40401865" }
>   }'
> ```
>
> `store_pick` says what happened. `selected: true` means the store is already selected at the merchant. When `selected` reads `false`, Agentcard selects the store while it writes its answer.
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Suavecito Birria & Tacos it is. The most popular picks:\n\n- Quesabirrias, $29.99: three birria tacos with cheese, dipped in beef stew\n- Shredded Beef Birria Taco, $7.49\n- Carne Asada Taco, $7.49\n- Pork Carnitas Taco, $5.99\n\nWhich tacos would you like, and how many?",
>   "store_pick": { "store_id": "40401865", "name": "Suavecito Birria & Tacos", "selected": true },
>   "catalog": {
>     "merchant": "doordash",
>     "merchant_name": "DoorDash",
>     "store": { "id": "40401865", "name": "Suavecito Birria & Tacos" },
>     "items": [
>       { "id": "40659654472", "ref": "p_3eb660f8f3ff", "name": "Quesabirrias", "priceCents": 2999, "currency": "usd", "image_url": "https://img.cdn4dd.com/...", "url": "https://www.doordash.com/store/40401865/" },
>       ...
>     ]
>   }
> }
> ```

### Handle a store no longer listed

Agentcard keeps the stores of a search for 15 minutes, and a newer search replaces them. A pick of a store Agentcard no longer keeps selects nothing. Send the shopper's words again without the store's id, and Agentcard searches again.

> [tab] SDK
>
> The model reads that the pick selected nothing and that it should search again with the shopper's words.

> [tab] MCP
>
> Call `buy` again with the shopper's words and `store_id: null`.

> [tab] API
>
> The pick is refused, and no store is selected:
>
> ```text theme={null}
> 409
> {
>   "error": "The picked store is not among this conversation's latest store search results any more, so no store was selected. Send the shopper's words as `ask` without `pick`, and the purchase agent searches again.",
>   "code": "store_pick_not_found",
>   "conversation_id": "conv_d8b4740ba88a1f0ed369a08d"
> }
> ```
>
> Send the same `ask` again without `pick`.

## Show the menu

The menu arrives as products, one for each dish, with the same fields as any product. The dishes of one store share the store's one page, so three dishes are three cards that open the same page. Render them as [Show products](https://docs.agentcard.com/opencommerce/guides/showing-products.md) shows, and put the one the shopper taps in the cart.

> [tab] SDK
>
> The dishes reach `sendLink` as links of kind `product`.

> [tab] MCP
>
> The dishes arrive in the result's `products`, each with its `product_id`. Call `buy` with the shopper's words and the dish's `product_id` to put it in the cart.

> [tab] API
>
> The dishes arrive in the `catalog` block, and `catalog.store` names the store they are from. Put the one the shopper taps in the cart with `pick.product_id`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "conversation_id": "conv_d8b4740ba88a1f0ed369a08d",
>     "external_user_id": "user-42",
>     "ask": "the carne asada taco",
>     "pick": { "product_id": "40659654480" }
>   }'
> ```

## Check it in the sandbox

The sandbox, Agentcard's test mode, searches real stores and stops before payment, so no order is placed.

1. As a test shopper, send `get me tacos delivered to 1 Market St, San Francisco, CA 94105`.
2. Check that stores arrive, each with a name, and that the reply asks which store.
3. Pick the second store by its id. Check that the next answer is that store's dishes and that no new store search ran.
4. After a new store search, send `the second one`. Check that the second store is selected.

> [tab] SDK
>
> 5. Check that each store card has a picture and a delivery time.

> [tab] MCP
>
> 5. Check that each store in `stores` has a `store_id` your code sends back unchanged.

> [tab] API
>
> 5. Send `pick.store_id` with an id the list never held. Check that the call answers `409` with `store_pick_not_found`.

DoorDash asks the shopper to sign in to their own account before checkout, as [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) shows.


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