Purchases

The Purchase API is a turn-based loop on one endpoint. You send what the user wants as plain text in ask, follow up with the same conversation_id, and place a shown cart by echoing its hash in confirm. Money moves only on a confirm, and only for exactly the cart the hash describes. The bearer names one person, because a purchase always runs as one user. A user token names that person itself: the connection access_token or a cardholder buy_token. A company that calls from its own server sends its platform access token and names the connected person with user_id, in the body of a POST and in the query of a GET. Use a client timeout of at least 120 seconds.

The purchase response object

Every 200 from POST /buy carries the same envelope. Each field is always present and null when empty.

Field	Type	Description
`conversation_id`	string	The thread. Send it back on every follow-up.
`status`	string	`needs_input`, `order_placed`, `partially_placed`, `declined`. The only field you branch on.
`reply`	string	The assistant’s turn as prose. `messages` carries it split into chat bubbles.
`cart`	object or null	The most recently shown cart. See below.
`carts`	array	Every open cart in the conversation, each with its own `hash`.
`catalog`	object or null	The last product search as data. See below.
`unmatched`	array	Asks that did not make it into a cart: `{ merchant, requested, reason, detail, at }`.
`order_id`	string or null	Set when this call placed an order. Reconcile on it.
`payment_source`	object or null	`{ source, brand, last4 }`. `source` is `balance`, `added_card`, `vault`, `company_balance`, or `stored_payment_method`.
`decline_code`	string or null	`vault_approval_required`, `byoc_approval_required`, `max_total_below_estimate`, `sandbox_mode`, `items_unavailable`, `unsupported_currency`, `currency_changed`, `no_cart`, … `in_progress` means another attempt (usually Agentcard placing the order the moment the approval landed) holds this checkout: wait ten seconds and read `GET /buy/conversations/{id}` rather than confirming again. The payment refusal codes are listed with what to do next on `order.failed`.
`approval_url`	string or null	Send to the user when the confirm paused.
`charge_status`	string or null	`none`, `confirming`, `settled`, `unknown`.
`merchant_total_cents`	integer or null	The merchant’s own total for a cart priced outside US dollars, in that currency’s smallest unit. Null for a US dollar cart.
`merchant_currency`	string or null	The merchant’s currency as a lower-case code, `cad`. Null for a US dollar cart.
`placements`	array or null	Per-cart outcomes of a multi-cart confirm.
`error_code`	string or null	Machine-readable loop failure.

max_total_below_estimate means the max_total_cents sent with the confirm is below what the cart costs before shipping and tax. Nothing was charged. Confirm the same cart again with a higher cap.

The cart object

Field	Type	Description
`merchant`, `merchant_name`	string	Merchant id (`retail`, `doordash`, …) and display name.
`items[]`	array	`{ name, qty, priceCents, product_id }`.
`serviceFeesCents`, `tipCents`, `totalCents`	integer	The all-in total the user approves.
`approvedCeilingCents`	integer or null	The most a confirm can authorize when tax and shipping finalize later; null when equal to the total. Send `max_total_cents` with `payment_source: "vault"` on the confirm to approve less; a purchase paid from the balance or from an added card ignores the cap.
`chargeUpToNote`	string, optional	The explanation stored with the shown quote when `approvedCeilingCents` exceeds `totalCents`. Omitted when no explanation was stored, including older carts, or when no higher ceiling applies.
`hash`	string	Identifies exactly this cart at this price. Echo it in `confirm`.

The presence of chargeUpToNote does not establish that the assistant repeated the explanation in reply.

{
  "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" }],
  "serviceFeesCents": 56,
  "tipCents": 0,
  "totalCents": 2306,
  "approvedCeilingCents": 3444,
  "hash": "9f2c4a1b8e3d5f07"
}

The catalog object

Show your own product list from catalog instead of reading the results out of reply. catalog holds the last product search in the conversation, on the turn that searched and on the turns after it. Fifteen minutes after that search, catalog is null, because prices and item ids can change by then. Send a new ask to search again.

Field	Type	Description
`merchant`, `merchant_name`	string	Merchant id and display name. `merchant_name` names the store for `retail`, such as `Amazon`, and the merchant otherwise, such as `DoorDash`.
`store`	object or null	The `id` of the store searched, and its `name` when known. `null` when the search covered several stores.
`store.eta_minutes`	integer or null	A delivery store’s estimate in minutes when the search ran, `null` when it showed none. Absent for other merchants.
`items[]`	array	Up to 20 results: `{ id, name, priceCents, image_url }`. Only `id` is always present.
`items[].reservation.searchedDatetime`	string, optional	For dining results, the date and time sent to the reservation provider in the search query. The value records the search input and does not establish that a table is available at that time.
`as_of`	string	When the search ran, ISO 8601.

Match a retail cart line to its search result: the line’s product_id and the item’s id are the same product page URL. Other merchants use their own item id. Check for priceCents before you show a price. An item leaves out a field it does not have instead of sending null, unlike the fields of the purchase response object. A restaurant reservation time slot never has a price. A retail search drops any product listed without a price, because a cart cannot hold it. An item without a picture has no image_url.

{
  "merchant": "retail",
  "merchant_name": "Amazon",
  "store": null,
  "items": [
    {
      "id": "https://www.amazon.com/dp/B00R92W0AU",
      "name": "Folgers 100% Colombian Medium Roast Ground Coffee, 10.3 Ounces",
      "priceCents": 1595,
      "image_url": "https://m.media-amazon.com/images/I/81Xh6IS8O7L._AC_UL320_.jpg"
    },
    {
      "id": "https://www.amazon.com/dp/B07P5LD4V8",
      "name": "Folgers 100% Colombian Coffee, Medium Roast Ground Coffee, 9.6 Ounce Canister",
      "priceCents": 1024,
      "image_url": "https://m.media-amazon.com/images/I/816JHMYPHFL._AC_UL320_.jpg"
    }
  ],
  "as_of": "2026-09-28T19:26:04Z"
}

Show image_url where your app can render an image (a chat bubble, a card) and send id when the user wants the page. Both come from the merchant; never build either from the name.

Endpoints

Endpoint
`POST /buy`	Buy: ask, follow up, confirm
`GET /buy/merchants`	List the merchants `/buy` can place at
`GET /buy/conversations/{id}`	Read a purchase conversation: reconcile a confirm whose response never arrived
`GET /buy/orders/{order_id}`	Read where an order is: the delivery stage and the arrival estimate

Webhooks: order.placed, order.failed, order.confirmed, order.updated. The guide is Agentcard’s Purchase API.

Overview

Access tokens

Connections

Vault

Cards

Identity verification

Webhook endpoints

Blooio connection

Purchases

The purchase response object

The cart object

The catalog object

Endpoints

​The purchase response object

​The cart object

​The catalog object

​Endpoints

The purchase response object

The cart object

The catalog object

Endpoints