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

# Send a dispute to the right place

> Read who charged the shopper's card for an order, and tell the shopper where a return or a dispute goes.

A shopper who wants their money back asks two things: who charged me, and who do I talk to. Each placed order answers both in `merchant_of_record`. Read it, and your app tells the shopper where to go without asking Agentcard.

## Read who charged the card

`merchant_of_record` has four fields:

| Field | Value |
| - | - |
| `name` | Who charged the card, such as `DoorDash` or `Agentcard`. |
| `kind` | `store` when the store charged at its own checkout, `seller` when the seller of the product charged, `agentcard` when Agentcard charged. |
| `statement_name` | What the shopper's card statement reads, such as `DOORDASH*BURGER BARN`, or `AGENTCARD CORPORATION` where Agentcard charged the card. `null` when Agentcard has not seen the charge yet. |
| `dispute_with` | `card_bank` when the shopper's own card paid, `agentcard` when money held in an Agentcard balance paid. |

The whole field is `null` for an order whose payer Agentcard does not know yet. Show nothing about who charged in that case, and send the shopper to Agentcard support if they ask.

The field sits on each order in a read of the whole purchase, on a read of one order, and on the [`order.placed`](https://docs.agentcard.com/webhooks/orders/order-placed) event. Agentcard sends that event to your webhook endpoint, the address on your server where Agentcard sends a request when something happens.

> [tab] SDK
>
> `agentcard.conversation()` reads the whole purchase, and each order in its `orders` list carries `merchant_of_record`:
>
> ```ts orders.ts theme={null}
> const { orders } = await agentcard.conversation(conversationId, { externalUserId: shopper.id });
> const mor = orders[0].merchant_of_record;
> // { name: 'Agentcard', kind: 'agentcard', statement_name: 'AGENTCARD CORPORATION', dispute_with: 'card_bank' }
> ```
>
> In a webhook handler, read the event's field with `merchantOfRecordOf()`, which returns the same shape, or `null` for a value it cannot read:
>
> ```ts webhooks.ts theme={null}
> import { merchantOfRecordOf } from '@agent-cards/commerce-sdk';
>
> const mor = merchantOfRecordOf(event.data.merchant_of_record);
> ```

> [tab] MCP
>
> No MCP tool returns `merchant_of_record` yet. [`get_order`](https://docs.agentcard.com/commerce-mcp/tools/get_order) returns the store, `merchant_name`, and the store's own order number, `retailer_order_id`, but not who charged the card.
>
> Read who charged from the `order.placed` event at your webhook endpoint, or from the API's read of one order, as the API tab shows. Your client ID and secret get an access token there, and your `shopper_id` is the `external_user_id`.

> [tab] API
>
> `GET /buy/orders/:order_id` reads one order. `order_id` is the id the `order.placed` event carried. Send the shopper's `external_user_id` in the query:
>
> ```bash theme={null}
> curl "https://api.agentcard.sh/buy/orders/ord_7f3a91c2?external_user_id=user-42" \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "order_id": "ord_7f3a91c2",
>   "merchant": "retail",
>   "merchant_name": "Amazon",
>   "conversation_id": "conv_ddaaf96c052893b13209e6c9",
>   "status": "confirmed",
>   ...
>   "merchant_of_record": {
>     "name": "Agentcard",
>     "kind": "agentcard",
>     "statement_name": "AGENTCARD CORPORATION",
>     "dispute_with": "card_bank"
>   }
> }
> ```
>
> `GET /buy/conversations/:id` reads the whole purchase, with the same field on each order in `orders`. A purchase with two orders can hold one of each:
>
> ```json theme={null}
> {
>   "orders": [
>     { "order_id": "ord_51c0e8", "merchant": "flights", "merchant_of_record": { "name": "Agentcard", "kind": "agentcard", "statement_name": null, "dispute_with": "card_bank" }, ... },
>     { "order_id": "ord_9d2b47", "merchant": "retail", "merchant_name": "Walmart", "merchant_of_record": null, ... }
>   ]
> }
> ```
>
> In the `order.placed` event, the field is `data.merchant_of_record`.

## Send a return first

A return goes to the party in `name` first. A DoorDash order with a missing item is DoorDash's to refund, so the shopper asks DoorDash before they open a dispute. When `kind` is `agentcard`, the shopper asks Agentcard support for the return, with the order number.

## Send a dispute

A dispute is a request to the shopper's bank, or to Agentcard, to take a charge back. When a return fails, `dispute_with` says who handles it.

With `card_bank`, the shopper paid with their own card, such as the card saved in the Vault, Agentcard's page where the shopper saves their card and approves a payment. The shopper opens the dispute with their bank. Agentcard keeps the record of what the shopper approved with their passkey, the store and the amount, as evidence for that dispute.

With `agentcard`, the order was paid from money held in an Agentcard balance, through a card Agentcard issued for that one order. The shopper has no bank to call. Agentcard handles the dispute, so send the shopper to Agentcard support with the order number.

## Match the statement line

A shopper who does not recognize a charge compares it with `statement_name`. A statement can read Agentcard instead of the store when Agentcard charged the card. An order at a large store such as Amazon, Walmart or Target, whose `merchant` reads `retail`, is charged by Agentcard when the shopper pays with their own card. Its `statement_name` reads `AGENTCARD CORPORATION` and `merchant_of_record.name` reads `Agentcard`, while the order's `merchant_name` reads `Amazon`. Show both, so the shopper links the line on their statement to the order they placed.

## Show who sells the product

`fulfilled_by` names who sells or books a product, and `merchant_of_record` names who charged the card. The two often differ. A flight is flown by its airline, so its `fulfilled_by` names Delta, while Agentcard booked it and charged the card, so `merchant_of_record.name` reads `Agentcard`.

A product carries `fulfilled_by` only where the seller is not the store the product already names. A product at Amazon or at a store's own website carries none. Show the seller's line beside the product, and `merchant_of_record` beside the charge.

> [tab] SDK
>
> On a product card the SDK hands back, `fulfilled_by` carries `name`, `kind` and `line`, the words to show, such as `flown by Delta`. On a raw answer or an event, `fulfilledByOf(value)` returns the same fields, and `null` for a party it cannot read.
>
> ```ts cards.ts theme={null}
> import { fulfilledByOf } from '@agent-cards/commerce-sdk';
>
> const seller = fulfilledByOf(product.fulfilled_by); // product: one item of a raw answer's catalog
> // { name: 'Delta', kind: 'airline', line: 'flown by Delta' }
> ```

> [tab] MCP
>
> Each product in a `buy` result carries `fulfilled_by` as the line to show, or `null`. A sandbox search for Knicks tickets returned:
>
> ```json theme={null}
> {
>   "product_id": "p_2a7c7e831a79",
>   "name": "Utah Jazz at New York Knicks",
>   "store": "Tickets",
>   "url": "https://www.stubhub.com/new-york-knicks-new-york-tickets-12-23-2026/event/161658877/",
>   "action": "book",
>   "fulfilled_by": "via StubHub"
> }
> ```

> [tab] API
>
> `fulfilled_by` appears on a product in `catalog.items` and on a cart line as `{ "name": "Delta", "kind": "airline" }`. Build one short line from `kind`:
>
> | `kind` | Line to show |
> | - | - |
> | `marketplace` | `via StubHub` |
> | `seller` | `sold by Gomry` |
> | `booking_provider` | `booked with OpenTable` |
> | `airline` | `flown by Delta` |
> | `hotel` | `booked with Marriott` |


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