> ## 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 products and add the pick

> Show a card for each product Agentcard finds, and add the exact product the shopper picks to the cart.

The shopper asks for something, and your app shows a card for each product Agentcard found, with its name, price and picture. The shopper taps one, and Agentcard adds exactly that product to the cart, with no new search.

## Read the products

Send the shopper's words, such as "two packs of AA batteries from amazon". When Agentcard searched, the answer lists the products it found, at most eight.

> [tab] SDK
>
> Pass `sendLink` to `buy.turn`. Agentcard hands it one `product` link for each product a search finds, and the turn waits for your callback before the model answers:
>
> ```ts chat.ts theme={null}
> const turn = buyFor(shopper.id).turn(message, {
>   sendLink: (link) => {
>     if (link.kind === 'product') return sendProductCard(shopper.id, link); // your code
>     return deliverStepLink(shopper.id, link); // card, approval and store sign-in links
>   },
> });
> ```
>
> The model never reads a link. It reads `product_links_sent`, the number of cards the shopper holds, and writes one short line beside the cards instead of listing the products again. A shopper who asks for links hears that the links are there.
>
> A `sendLink` that throws on a product link counts that product as not sent, and the call goes on. The model reads `link_sent: false` on that product. A throw on a card or approval link makes the call throw too.

> [tab] MCP
>
> Call [`buy`](https://docs.agentcard.com/commerce-mcp/tools/buy) with the shopper's words in `ask`:
>
> ```json theme={null}
> {
>   "tool": "buy",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "ask": "two packs of AA batteries from amazon",
>     "confirm": false,
>     "new_order": false,
>     "product_id": null,
>     "store_id": null
>   }
> }
> ```
>
> The result lists the products in `products`. This result is shortened to one product:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Which pack size do you want two of? ...",
>   "products": [
>     {
>       "product_id": "p_0a02f4ebb745",
>       "name": "Amazon Basics 20-Pack AA Alkaline Batteries",
>       "store": "Amazon",
>       "price": { "amount_cents": 999, "currency": "USD" },
>       "price_text": "$9.99",
>       "url": "https://www.amazon.com/dp/B00NTCH52W",
>       "image_url": "https://m.media-amazon.com/images/I/81U2sRlmzNL._AC_UL320_.jpg"
>     }
>   ],
>   "conversation_id": "conv_527d0e58fbd792e797b4d099"
> }
> ```
>
> When your app shows the products as cards, have your agent write one short line beside them instead of listing the products again.

> [tab] API
>
> Send the shopper's words as `ask`, with your own id for the shopper as `external_user_id`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{ "ask": "two packs of AA batteries from amazon", "external_user_id": "user-42" }'
> ```
>
> The answer carries a `catalog` object, and `catalog.items` lists the products:
>
> ```json theme={null}
> {
>   "conversation_id": "conv_527d0e58fbd792e797b4d099",
>   "status": "needs_input",
>   "reply": "Which pack size do you want two of? ...",
>   "catalog": {
>     "merchant": "retail",
>     "merchant_name": "Amazon",
>     "presented": true,
>     "items": [
>       {
>         "id": "https://www.amazon.com/dp/B00NTCH52W",
>         "ref": "p_0a02f4ebb745",
>         "name": "Amazon Basics 20-Pack AA Alkaline Batteries, 1.5 Volt, 10-Year Leak-Free Shelf Life, for Everyday and Household Devices",
>         "priceCents": 999,
>         "currency": "usd",
>         "image_url": "https://m.media-amazon.com/images/I/81U2sRlmzNL._AC_UL320_.jpg",
>         "store": { "id": "amazon", "name": "Amazon", "domain": "amazon.com" },
>         "url": "https://www.amazon.com/dp/B00NTCH52W"
>       },
>       ...
>     ]
>   }
> }
> ```
>
> Keep `conversation_id`, the id of this purchase, and send it back on every later call about it.
>
> Show the cards only when `catalog.presented` is `true`. An answer that only moves the purchase along, such as a question about the address, can still carry the last search's `catalog` with `presented: false`, and showing it again repeats cards the shopper already has.

## Show each product

Show the picture, the name, the price and a button. Show the store's website as where the product comes from, never the host of the product's page link, because that link can pass through a tracking page before the store. When a product has more than one photo, show the others as thumbnails that swap the main picture.

Word the button for what taking the product does: Reserve for a restaurant table, Book for a flight, room, class or ticket, and Buy for anything else.

Write each price in the product's own currency. An amount of `1331` in the smallest unit of the currency reads `\$13.31` in USD, `CA\$13.31` in CAD and `¥1,331` in JPY. A product whose price depends on a choice the shopper still makes, such as a size, shows as "from \$9.99".

> [tab] SDK
>
> A `product` link carries these fields:
>
> | Field | Type | What it holds |
> | - | - | - |
> | `title` | string | The product's name. |
> | `price` | string or null | The price the shopper reads, such as `$12.99`, or `from $10.69` for a product priced by a choice. |
> | `url` | string or null | The product's page at its store. Null for a flight. |
> | `store` | string or null | The store that sells it, such as `Walmart`. |
> | `storeDomain` | string or null | The store's website, such as `walmart.com`. Null for a store with no website, such as a restaurant. |
> | `imageUrl` | string or null | The product's picture, or null when the store sent none. |
> | `images` | string\[] | Every photo, `imageUrl` first, at most eight. |
> | `productId` | string | Agentcard's id for the product. It holds no link. |
> | `action` | `buy`, `reserve` or `book` | What taking the product does. Word the button from it. |
>
> The SDK writes `price` in the product's own currency for you. A price in a currency Agentcard does not name shows with no symbol.

> [tab] MCP
>
> Each entry in `products` carries `product_id`, `name`, `store`, `price`, `price_text`, `url` and `image_url`. Show `price_text` as the price, or format `price` yourself: it is `{ amount_cents, currency }`, so `{ "amount_cents": 999, "currency": "USD" }` is \$9.99.
>
> Keep `product_id` for the pick. Never show it to the shopper.

> [tab] API
>
> Each entry in `catalog.items` holds one product:
>
> | Field | Type | What it holds |
> | - | - | - |
> | `ref` | string | Agentcard's id for the product, with no link in it. Send it back when the shopper picks this product. |
> | `id` | string | The product's id at its store, which can be its web address. A pick takes it too. |
> | `name` | string | The product's name. |
> | `priceCents` | number | The price in the smallest unit of `currency`, so `999` in `usd` is `$9.99`. |
> | `price_from` | `true`, optional | Present when the price depends on a choice the shopper still makes. Show it as "from". |
> | `currency` | string | The currency's three-letter code, such as `usd`. |
> | `image_url` | string, optional | The product's picture. Absent when the store sent none. |
> | `image_urls` | string\[], optional | Every photo, `image_url` first, at most eight. Present only when there is more than one. |
> | `store` | object | The store: `name`, and `domain`, its website. `domain` is null for a store with no website. |
> | `url` | string or null | The product's page. Null for a flight. |
>
> Word the button from `catalog.merchant`: Reserve for `reservations`, Book for `flights`, `hotels`, `cars`, `tickets` and `classes`, and Buy for anything else.
>
> A product with `browse_only: true` is at a store Agentcard does not buy from for your app. Show it to look at, with no buy button.

### Show a flight

A flight has no page at a store, so its page link is null. The airline, the route and the times are in its name, and the API also carries a `flight` object with each leg's airports and times. Show it as a card with no link to open, and send its id back when the shopper picks it.

## Add the one the shopper picks

When the shopper taps a card, send their words and the product's id. Agentcard adds exactly that product from the list it showed, and runs no new search. The shopper's words still count: "two of the 20-pack" sets the quantity to two.

A shopper who picks by typing, such as "the second one", needs no id at all. Send their words, and Agentcard reads which product they mean from the list it showed.

> [tab] SDK
>
> Each product in the model's view carries a `product_id`. When the shopper picks a product by its name, its place in the list or a tap on its card, the model passes that `product_id`. A Buy button that sends the shopper's words is enough:
>
> ```text theme={null}
> i'll take the KODAK AA Alkaline Batteries (24 Pack) ($13.49)
> ```
>
> The model reads the `product_id` beside that name in its last result, so keep every tool result in the model's history, as a tool runner does. Without the history, the model no longer holds the ids on the shopper's next message.
>
> Your own code can pick too. A card's button can call `buy.answer` with the link's `productId`:
>
> ```ts cart-button.ts theme={null}
> const result = await buyFor(shopper.id).answer({
>   ask: link.title ?? '',
>   confirm: false,
>   new_order: false,
>   product_id: link.productId, // from the product link, never typed by the shopper
> });
> ```
>
> `result.pick` holds the product's `product_id` and `in_cart`, whether the cart now holds it. The model reads the same `pick`.

> [tab] MCP
>
> Call `buy` again with the shopper's words and the product's `product_id`. Never send `product_id` together with `store_id`:
>
> ```json theme={null}
> {
>   "tool": "buy",
>   "arguments": {
>     "shopper_id": "user_8f3a21",
>     "thread_id": "chat_5521",
>     "ask": "two of the 20-pack",
>     "confirm": false,
>     "new_order": false,
>     "product_id": "p_0a02f4ebb745",
>     "store_id": null
>   }
> }
> ```
>
> The result's `carts` holds the cart with the product in it.

> [tab] API
>
> Send the shopper's words as `ask` and the card's `ref` as `pick.product_id`, with the same `conversation_id`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "conversation_id": "conv_527d0e58fbd792e797b4d099",
>     "external_user_id": "user-42",
>     "ask": "two of the 20-pack",
>     "pick": { "product_id": "p_0a02f4ebb745" }
>   }'
> ```
>
> The answer's `pick` object says what happened:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Added 2 Amazon Basics 20-Pack AA Alkaline Batteries from Amazon to your cart, about $20.48 in total. ...",
>   "pick": {
>     "product_id": "https://www.amazon.com/dp/B00NTCH52W",
>     "ref": "p_0a02f4ebb745",
>     "in_cart": true
>   },
>   "cart": { ... },
>   "next_action": "shipping_details"
> }
> ```
>
> `pick.in_cart` is `true` when the cart now holds the product.

[Show the cart and confirm it](https://docs.agentcard.com/opencommerce/guides/showing-the-cart.md) covers how to show the cart that comes back.

### Handle a product that is gone

Agentcard keeps a search's products for 15 minutes, and a newer search in the same conversation replaces them. A pick of a product Agentcard no longer keeps adds nothing.

> [tab] SDK
>
> The answer reads `needs_input` with `error_code: pick_not_found`, and the model reads this line:
>
> ```text theme={null}
> The product the shopper picked is no longer among the products Agentcard found, so nothing was added. Call this tool again with the shopper's words and product_id null, and Agentcard searches again.
> ```
>
> The model then searches again with the shopper's words.

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

> [tab] API
>
> The call is refused:
>
> ```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": "conv_527d0e58fbd792e797b4d099"
> }
> ```
>
> Send the same call again without `pick`. Agentcard searches again with the shopper's words.

### Handle a pick not yet added

A pick can leave the cart without the product, and the reply says why. At a store where Agentcard fills in the store's own checkout page, that page often needs the delivery address before it takes the product. Show the reply to the shopper and send their answer as the next message. The product goes into the cart once the store has what it needs, so ask for no payment until a later answer carries the cart.

> [tab] SDK
>
> `result.pick.in_cart` reads `false`. The model tells the shopper what Agentcard said, and it asks for no card and no yes for an older cart.

> [tab] MCP
>
> The result's `carts` holds no line for the product, and `next_action` names the step to ask for, such as `shipping_details`.

> [tab] API
>
> `pick.in_cart` reads `false`:
>
> ```json theme={null}
> {
>   "status": "needs_input",
>   "reply": "Where should the order from duralexusa.com be delivered? Send me the street address, or a place name and I'll look it up.",
>   "next_action": "shipping_details",
>   "pick": {
>     "product_id": "shopify:duralexusa.com:590144077883",
>     "ref": "p_b060be899fd0",
>     "in_cart": false
>   }
> }
> ```

## Check it in the sandbox

The sandbox, Agentcard's test mode, searches real stores and stops before payment, so it places no order and charges nothing. Sandbox credentials run every call there.

1. Send "two packs of AA batteries from amazon" as a test shopper, such as `docs-test-1`.
2. Check that products arrive, each with a name, a price and a picture.
3. Pick one. Check that the cart holds that product and that Agentcard ran no new search.
4. Wait more than 15 minutes, pick a product from the old search, and check that nothing is added and Agentcard searches again.


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