Agentcard's Purchase API

Use Agentcard’s Purchase API to let your agent buy things online without building merchant integrations or using an agent browser. Merchants supported today include Amazon, Walmart, Target, Best Buy, and many more.

Where agents can buy

Here are a few examples of merchants supported today:

Amazon

Walmart

Target

Best Buy

Home Depot

Lowe’s

Macy’s

Wayfair

Staples

Kohl’s

B&H Photo

DoorDash

Good Eggs

Locale

Flights

For the live list, call GET /buy/merchants with the same bearer token you send to /buy.

What you need

A user with a card in the Vault (Adding a card).
A user-scoped bearer token.
- /buy always runs as a single user, so org tokens are rejected.
- Use the user’s connection access_token, or mint a buy_token for a cardholder you own:

curl -X POST https://api.agentcard.sh/api/v1/cardholders/CARDHOLDER_ID/buy_token \
  -H "Authorization: Bearer $ORG_TOKEN"

Recommended: set a client timeout of at least 120 seconds. Each turn runs against a live merchant.

Quickstart

Every call is a POST /buy. A single purchase follows a turn-based loop, tied together by conversation_id.

1) Start (send an ask)

curl -X POST https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ask": "a 16 oz bag of Colombian ground coffee from Amazon, ship it to 1900 Jefferson St, San Francisco"}'

2) Loop: reply → ask (until a cart is ready)

If the API needs more info, it responds with status: "needs_input" and a natural-language reply. Show reply to the user, then send the user’s answer back as the next ask with the same conversation_id:

curl -X POST https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "cmsq18x2m00a1", "ask": "the Cafe Mesa one"}'

Repeat this loop as needed. Nothing can be charged during it.

3) Read the cart (use structured fields)

Once the API has enough details, the response includes a cart and a cart.hash. Use these structured fields (not the prose) to show the user exactly what will be purchased.

{
  "conversation_id": "cmsq18x2m00a1",
  "status": "needs_input",
  "reply": "Found it. Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz, at $22.50. Total $23.06 shipping to 1900 Jefferson St. Want me to place it?",
  "cart": {
    "merchant": "retail",
    "merchant_name": "Amazon",
    "items": [
      { "name": "Cafe Mesa de los Santos Colombian Ground Coffee, 16 oz", "qty": 1, "priceCents": 2250, "product_id": "https://www.amazon.com/dp/B07ZQ5C4RB" }
    ],
    "totalCents": 2306,
    "hash": "9f2c4a1b8e3d5f07"
  },
  "unmatched": []
}

Notes:

unmatched lists anything requested that didn’t make it into the cart (plus a reason). Show it instead of guessing from the prose.
The status can still be needs_input here, because the API is asking for confirmation.
If the user wants a change (for example, “make it two bags”), send that as another ask. You’ll get an updated cart with a new hash.

4) Confirm the cart hash (and choose a payment source)

When the user wants to proceed, confirm the exact cart you showed by sending the cart.hash (not a free-form “yes”). To pay with the user’s own card, pass payment_source: "vault".

curl -X POST https://api.agentcard.sh/buy \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "cmsq18x2m00a1", "confirm": "9f2c4a1b8e3d5f07", "payment_source": "vault"}'

5) If approval is required: send the approval URL, then retry confirm

A confirm may pause while the user approves:

{
  "conversation_id": "cmsq18x2m00a1",
  "status": "declined",
  "decline_code": "vault_approval_required",
  "approval_url": "https://vault.agentcard.sh/authorize?id=cauth_2q9d1x8f3k2m4t7w",
  "charge_status": "none"
}

This is a pause, not a verdict. Nothing was charged. Send approval_url to the user. After they approve (Face ID), repeat the same confirm call from step 4. When the purchase is placed:

{
  "conversation_id": "cmsq18x2m00a1",
  "status": "order_placed",
  "reply": "Order placed at Amazon. Charged $23.06 to your Visa ending 4832.",
  "order_id": "3f9a8c1b-7d2e-4c5a-9b1f-2e8d4a6c0b17",
  "payment_source": { "source": "vault", "brand": "visa", "last4": "4832" },
  "charge_status": "settled"
}

The fields you branch on

Field	Values	Use it to
`status`	`needs_input`, `order_placed`, `partially_placed`, `declined`	Decide what to do next. Never branch on `reply`.
`cart.hash`	string	Confirm exactly this cart.
`decline_code`	`vault_approval_required`, `items_unavailable`, …	Tell an approval pause from a real decline.
`approval_url`	string or null	Send to the user when the confirm paused.
`charge_status`	`none`, `confirming`, `settled`, `unknown`	Tell the user whether money moved.
`order_id`	string or null	Reconcile and track.

Edge cases

If the price changed

A confirm authorizes one cart at one price. If anything drifted since the cart was shown, confirm returns 409 with a fresh cart and a new hash. Show the user the new total, then confirm the new hash.

Track the order

Retail orders confirm asynchronously (often ~1 minute after placement).

curl "https://api.agentcard.sh/buy/v1/merchants/retail/orders/ORDER_ID/track" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

This returns the retailer’s order number, delivery window, final total, and shipments once a package ships. Or listen for the order.placed and order.confirmed webhooks instead of polling.

If a confirm times out

Don’t resend. First, read the conversation:

curl https://api.agentcard.sh/buy/conversations/CONVERSATION_ID \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

Wait for turn_in_progress to clear, then check orders. A duplicate confirm while a turn is running returns 409 turn_in_progress, so the same cart can never place twice.

Over MCP

The same loop is available as the buy tool on https://mcp.agentcard.sh/mcp, using the same bearer. The agent relays each turn, the user confirms in words, and the tool places the order.

Sandbox

Sandbox runs the real loop against real merchants up to the confirm. The confirm returns declined with decline_code: "sandbox_mode" by design, because sandbox cards can’t pay a real merchant. Everything before it (conversation, cart, hash) is identical to production.

Getting started

Vault

Issuing

Agentcard's Purchase API

Where agents can buy

What you need

Quickstart

1) Start (send an ask)

2) Loop: reply → ask (until a cart is ready)

3) Read the cart (use structured fields)

4) Confirm the cart hash (and choose a payment source)

5) If approval is required: send the approval URL, then retry confirm

The fields you branch on

Edge cases

If the price changed

Track the order

If a confirm times out

Over MCP

Sandbox

​Where agents can buy

​What you need

​Quickstart

​1) Start (send an ask)

​2) Loop: reply → ask (until a cart is ready)

​3) Read the cart (use structured fields)

​4) Confirm the cart hash (and choose a payment source)

​5) If approval is required: send the approval URL, then retry confirm

​The fields you branch on

​Edge cases

​If the price changed

​Track the order

​If a confirm times out

​Over MCP

​Sandbox

Where agents can buy

What you need

Quickstart

1) Start (send an ask)

2) Loop: reply → ask (until a cart is ready)

3) Read the cart (use structured fields)

4) Confirm the cart hash (and choose a payment source)

5) If approval is required: send the approval URL, then retry confirm

The fields you branch on

Edge cases

If the price changed

Track the order

If a confirm times out

Over MCP

Sandbox