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

# Check where Agentcard can pay

> Ask Agentcard whether it can buy at a store before your agent sends a shopper there.

Ask Agentcard whether it can buy at a store before your agent offers it to a shopper. One lookup names the store, says how Agentcard pays there, and says whether recent purchases there went through. The lookup reads a list and buys nothing.

The list is the same in the sandbox, Agentcard's test mode, and in production. Sandbox credentials read it in the sandbox.

With a shopper in the chat, your agent does not need this lookup. Send the shopper's ask, and Agentcard answers whether it can buy at the store they named.

## Look up one store

Pass the store's name or domain, such as `target` or `bose.com`.

> [tab] SDK
>
> Call `agentcard.merchants` with the store as `q`. `q` also takes a full link to any page of the store, and Agentcard drops the `https://`, the `www.` and the path for you:
>
> ```ts merchants.ts theme={null}
> const page = await agentcard.merchants({ q: 'https://www.bose.com/c/headphones' });
> const bose = page.merchants.find((m) => m.domain === 'bose.com');
> ```
>
> `page` holds the same `merchants`, `next_cursor` and `counts` as the API tab shows. Call it with your company credentials and no shopper to read each store as a shopper of your app reads it before signing in anywhere.

> [tab] MCP
>
> Call [`list_merchants`](https://docs.agentcard.com/commerce-mcp/tools/list_merchants) with part of the store's name or domain as `q`:
>
> ```json theme={null}
> {
>   "tool": "list_merchants",
>   "arguments": {
>     "q": "target",
>     "limit": 2
>   }
> }
> ```
>
> ```json theme={null}
> {
>   "merchants": [
>     {
>       "kind": "direct",
>       "id": "retail",
>       "name": "Amazon, Walmart, Target & Best Buy",
>       "domain": null
>     },
>     {
>       "kind": "catalog",
>       "id": "store_4fad04ea92d94045faa7b72f",
>       "name": "Target",
>       "domain": "target.com",
>       "buys_through": "browser",
>       "supported": false,
>       "countries": ["US"]
>     }
>   ],
>   "next_cursor": null,
>   "counts": { "direct": 1, "catalog": 1 }
> }
> ```
>
> The store's id is `id` here, where the SDK and the API call it `slug`.

> [tab] API
>
> Call `GET /buy/merchants` with the store as `q`, and your company's access token, as [Get an access token](https://docs.agentcard.com/purchase-api/http.md#get-an-access-token) shows. `q` also takes a full link to any page of the store, and Agentcard drops the `https://`, the `www.` and the path for you:
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/merchants?q=https://www.bose.com/c/headphones" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "merchants": [
>     {
>       "kind": "catalog",
>       "slug": "store_7b4c7cf6748295f4bf8981ec",
>       "name": "Bose",
>       "domain": "bose.com",
>       "buys_through": "browser",
>       "supported": true,
>       "supported_reason": "reach_proven",
>       "supported_detail": null,
>       "supported_read_at": "2026-11-17T19:15:37.734Z",
>       "countries": ["US", "CA", "DE", "FR", "GB", "AU"],
>       "wallets": [{ "wallet": "vault", "status": "expected" }]
>     }
>   ],
>   "next_cursor": null,
>   "counts": { "direct": 0, "catalog": 1 }
> }
> ```

`supported: true` means a recent purchase at the store reached its final total, so your agent can send the shopper there. A name can match more than one store, so read `domain` before you trust a row.

## Read each field

A store Agentcard buys at with no account to link has `kind: "catalog"`. Its row carries these fields:

| Field | What it tells you |
| - | - |
| `slug`, or `id` in MCP | The store's id at Agentcard. A purchase names the store in plain words, so you rarely send it back. |
| `name`, `domain` | The store's name and its website. |
| `buys_through` | How Agentcard pays. `retail` means Agentcard places the order itself at a large store such as Amazon, Walmart or Target, with no card form. `browser` means Agentcard fills in the store's own checkout page. |
| `supported` | `true` when recent purchases there went through, `false` when the last one stopped, `null` when nobody tried in the last 14 days. |
| `countries` | Two-letter codes of the countries the store sells in. Empty when the store names none. |
| `supported_reason`, `supported_detail`, `supported_read_at` | Why `supported` reads as it does, where the last purchase stopped, and when Agentcard last read that evidence. SDK and API only. |
| `wallets` | The ways a shopper can pay there. SDK and API only. |
| `held_back` | Present only when the store keeps cancelling guest orders, as the next paragraph explains. SDK and API only. |

A store whose `buys_through` is `retail` reads `supported: true` with no reason, no detail and no date, because Agentcard places the order there itself and needs no card form.

A row with `held_back` names a store that cancelled orders Agentcard placed there as a guest. Until `held_back.until`, Agentcard offers the shopper another store, unless the shopper signed in to that store and checks out as themselves.

## Read why a store says no

`supported` describes what happened at the store lately. The field does not stop a purchase: your agent can still send a shopper to a store that reads `false` or `null`, and Agentcard tries. The SDK and the API say why in `supported_reason`, and the MCP tool returns `supported` alone.

| `supported_reason` | What it means | What to do next |
| - | - | - |
| `pay_proven` | A real order was paid at the store on `supported_read_at`. | Send shoppers there. |
| `reach_proven` | A purchase reached the store's final total at a payment form Agentcard can fill in. | Send shoppers there. |
| `gate_refused` | The store's payment form belongs to a payment company Agentcard cannot pay through, and `supported_detail` names it, such as `adyen`. A purchase there stops at payment. | Send the shopper to another store. |
| `unreached` | The last purchase stopped before the final total, and `supported_detail` says where. | Offer another store. Agentcard still tries when a shopper asks. |
| `null` | No evidence from the last 14 days, or the store's `buys_through` is `retail`. | Let the shopper try. |

At Hot Topic the last purchase stopped because the product was out of stock:

```json theme={null}
{
  "kind": "catalog",
  "slug": "store_649de3bd04705d8ce79f4cb7",
  "name": "Hot Topic",
  "domain": "hottopic.com",
  "buys_through": "browser",
  "supported": false,
  "supported_reason": "unreached",
  "supported_detail": "out_of_stock",
  "supported_read_at": "2026-11-06T06:12:00.065Z",
  "countries": ["US"],
  "wallets": [{ "wallet": "vault", "status": "expected" }]
}
```

A stop like `out_of_stock` was about one product, so a shopper buying something else there can still succeed. Values of `supported_detail` you can see today:

| `supported_detail` | Where the last purchase stopped |
| - | - |
| `account_required` | The store sells only to shoppers signed in to an account there. |
| `out_of_stock` | The product was sold out. |
| `bot_wall` | The store blocked Agentcard from its checkout page. |
| `total_unread` | The checkout page never showed a total Agentcard could read. |
| `progress_stalled` | The checkout page stopped moving forward. |

Treat a value you have not seen before the same way: the last try stopped at that store, and the next one may not.

## Read the wallets

In the SDK and the API, `wallets` lists the ways a shopper can pay at the store, each as `{ wallet, status }`. The Vault, Agentcard's page where the shopper saves their card and approves a payment, appears at every store. Stripe Link appears only at a store whose `buys_through` is `browser`, only for your production app, and only when your app offers Link. The MCP tool returns no wallets.

| `status` | What it means |
| - | - |
| `proven` | An order paid with that wallet was placed at the store. |
| `expected` | No order with that wallet yet, and nothing says it fails. |
| `refused` | The store turns that wallet away. Offer the shopper another way to pay. |

The SDK reads `wallets` as `null` from an older Agentcard.

## Handle a store not on the list

A store Agentcard does not list returns an empty page:

```json theme={null}
{ "merchants": [], "next_cursor": null, "counts": { "direct": 0, "catalog": 0 } }
```

Your agent can still send the shopper's ask. Agentcard answers that it could not search that store, and offers the same kind of product at stores it can buy at:

```text theme={null}
I couldn't search penzeys.com this time, so I can't say whether they have it. These jars are from other stores: ...
```

## Find the direct merchants

Some merchants Agentcard works with directly, such as DoorDash, flights and hotels. Their rows have `kind: "direct"`. Name the shopper with your own id for them to learn whether they still have to link an account there. `link_status: "unlinked"` means the shopper has not signed in to DoorDash through Agentcard yet, and Agentcard asks them to when they order there. A lookup that names no shopper returns the same row without `link_status`.

> [tab] SDK
>
> Name the shopper in the second argument:
>
> ```ts merchants.ts theme={null}
> const page = await agentcard.merchants({ q: 'doordash' }, { externalUserId: 'user-42' });
> ```

> [tab] MCP
>
> Pass the shopper as `shopper_id`:
>
> ```json theme={null}
> {
>   "tool": "list_merchants",
>   "arguments": {
>     "q": "doordash",
>     "shopper_id": "user_8f3a21"
>   }
> }
> ```

> [tab] API
>
> Pass the shopper as `external_user_id`:
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/merchants?q=doordash&external_user_id=user-42" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "merchants": [
>     {
>       "kind": "direct",
>       "slug": "doordash",
>       "name": "DoorDash",
>       "link_status": "unlinked",
>       "market": { "countries": ["US", "CA"], "currency": "USD" },
>       "capabilities": ["checkout", "store_search", "guest_browse", ...],
>       "flow": "store_delivery",
>       "scheduling": "scheduled",
>       "guest_browse": true,
>       "description": "a multi-store food/grocery delivery marketplace",
>       "wallets": [{ "wallet": "vault", "status": "expected" }]
>     }
>   ],
>   "next_cursor": null,
>   "counts": { "direct": 1, "catalog": 0 }
> }
> ```

An id that no shopper of your app carries is refused. Leave the shopper out to read the list as your company, or send the id of a shopper who has already made a purchase request in this mode. Sandbox and production shoppers are separate.

> [tab] SDK
>
> The call throws an `AgentcardApiError` whose `code` is `user_not_connected`.

> [tab] MCP
>
> The call fails with an error whose `code` is `user_not_connected`.

> [tab] API
>
> ```text theme={null}
> 403
> {"error":"user_not_connected","code":"user_not_connected","external_user_id":"docs-guide-refusals-1","message":"No person connected to your sandbox app carries the external_user_id \"docs-guide-refusals-1\". Sandbox and production users are separate: connect this person with your sandbox credentials, passing this external_user_id to the connect flow or the Vault link, then send it again."}
> ```

## List every store

Leave out `q` and set `kind`, which takes `direct`, `catalog` or `all`. Without `q` or `kind` the list holds only the direct merchants, and with `q` alone it holds both kinds. `limit` sets the page size, 50 by default and 100 at most.

`counts` says how many stores of each kind match, whatever page you are on. For the next page, send the same lookup with `cursor` set to the `next_cursor` you got, and repeat until `next_cursor` is `null`.

> [tab] SDK
>
> ```ts merchants.ts theme={null}
> let cursor: string | undefined;
> do {
>   const page = await agentcard.merchants({ kind: 'catalog', limit: 100, cursor });
>   for (const store of page.merchants) saveStore(store); // your code
>   cursor = page.next_cursor ?? undefined;
> } while (cursor);
> ```

> [tab] MCP
>
> ```json theme={null}
> {
>   "tool": "list_merchants",
>   "arguments": {
>     "kind": "catalog",
>     "limit": 100,
>     "cursor": "eyJrIjoiY2F0YWxvZyIsImEiOiIxMDBwZXJjZW50LmNvbSJ9"
>   }
> }
> ```

> [tab] API
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/merchants?kind=catalog&limit=2" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "merchants": [
>     { "kind": "catalog", "slug": "store_50e25648b23c5d5c0a5153f6", "name": "100Hands", "domain": "100hands.nl", ... },
>     { "kind": "catalog", "slug": "store_dc2d7aedeb3d41dfeed6c154", "name": "100 Percent", "domain": "100percent.com", ... }
>   ],
>   "next_cursor": "eyJrIjoiY2F0YWxvZyIsImEiOiIxMDBwZXJjZW50LmNvbSJ9",
>   "counts": { "direct": 11, "catalog": 6308 }
> }
> ```
>
> The request reads `cursor`, never `next_cursor`, so a request that sends `next_cursor` gets the first page again:
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/merchants?kind=catalog&limit=2&cursor=eyJrIjoiY2F0YWxvZyIsImEiOiIxMDBwZXJjZW50LmNvbSJ9" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```

## Fix a refused lookup

A lookup with a value Agentcard cannot read is refused, and the error's `code` says what to fix:

| `code` | Refused because | What to do |
| - | - | - |
| `invalid_kind` | `kind` is not `direct`, `catalog` or `all`. | Send one of the three values. |
| `invalid_limit` | `limit` is outside 1 to 100. | Send a whole number from 1 to 100. |
| `invalid_cursor` | `cursor` did not come from an earlier page. | Send `next_cursor` exactly as the last page returned it, with the same `kind`. |
| `invalid_query` | `q` was sent twice, or is longer than 100 characters. | Send one `q` of 100 characters or fewer. A long page link works once you cut it to the store's domain. |

> [tab] SDK
>
> The call throws an `AgentcardApiError` whose `code` is one of the codes above.

> [tab] MCP
>
> A bad argument fails with an error whose `code` is `invalid_input`. Fix the argument, and don't send the same call again.

> [tab] API
>
> The answer is `400` with the code. A `kind` outside the three values answers:
>
> ```text theme={null}
> 400
> {"error":"kind must be direct, catalog or all","code":"invalid_kind"}
> ```
>
> [Read a refusal](https://docs.agentcard.com/opencommerce/guides/reading-a-refusal.md) lists every refusal.


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