Look up one store
Pass the store’s name or domain, such astarget or bose.com.
- SDK
- MCP
- API
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:merchants.ts
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.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 haskind: "catalog". Its row carries these fields:
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.
At Hot Topic the last purchase stopped because the product was out of stock:
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:
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.
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:Find the direct merchants
Some merchants Agentcard works with directly, such as DoorDash, flights and hotels. Their rows havekind: "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.
- SDK
- MCP
- API
Name the shopper in the second argument:
merchants.ts
- SDK
- MCP
- API
The call throws an
AgentcardApiError whose code is user_not_connected.List every store
Leave outq 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.
- SDK
- MCP
- API
merchants.ts
Fix a refused lookup
A lookup with a value Agentcard cannot read is refused, and the error’scode says what to fix:
- SDK
- MCP
- API
The call throws an
AgentcardApiError whose code is one of the codes above.