Buy
One conversational endpoint that places real orders. Send the user’s request as plain text in ask; thread follow-ups with conversation_id; place a shown cart by echoing its hash in confirm (or an array of hashes for several carts). Money only moves on a confirm, and only for exactly the cart the hash describes.
Authorizations
The user's connection access_token (user authentication), or an org-minted buy_token for org-owned accounts.
Body
- Option 1
- Option 2
What the user wants, in plain language. Required unless the call is a confirm.
1\SThe thread to continue. A confirm always requires it.
1A cart hash from a previous response (16 hex characters), or an array of hashes to place several carts. An array confirm cannot carry an ask in the same call.
^[0-9a-f]{16}$Pay the confirmed cart(s) with the user's own vaulted card, whatever the user's wording: the confirm pauses with decline_code vault_approval_required and an approval_url, the user approves on their device, and the same confirm places the order. Confirm-only. Omit it and the loop keeps its default source.
vault The delivery address for this conversation, when your app manages the user's addresses. The agent ships to exactly these values, never asks the user to confirm or correct them, and does not read or update the wallet's saved default address for the conversation. Send it on any turn (the first is fine); it holds for the whole conversation, and a later turn's value replaces it. A malformed address is refused with 400 invalid_delivery_address before any turn runs.
Response
One turn of the purchase conversation, in the fixed envelope.
The fixed response envelope. Every field is present on every response, null when empty.
Thread it back on every follow-up. Returned on the first call too.
needs_input is progress, not failure: the reply is a question or a cart waiting on confirmation.
needs_input, order_placed, partially_placed, declined The assistant's turn as prose, ready to show a human.
The same turn split into ordered bubbles for chat surfaces.
The most recently shown cart. Null when no cart is on the table.
Every open cart in the conversation, oldest first. A conversation can hold carts at several merchants.
Per-cart outcomes of a multi-cart confirm; null on every other call. Partial success is representable here.
The last product search as data, with a freshness stamp. Null when nothing fresh was searched.
Machine-readable failure code when something went wrong.
Set when this call placed an order: the merchant's order id, or Agentcard's when the merchant returns none. The same key as order.orderId in GET /cards/transactions/by-payment-method and order_id on order.placed. Null on a multi-cart confirm (see placements).
What paid, or what would have paid. brand and last4 are the user's own card for added_card, vault and stored_payment_method; null for balance and company_balance, where no card of theirs is in the flow. Null when no checkout ran or it refused before resolving the source.
The machine code behind a declined: a gate reason (byoc_approval_required, vault_approval_required, sandbox_mode, per_txn_max_exceeded, card_limit_reached, ...) or a merchant code (items_unavailable, pos_cart_validation). in_progress means another attempt holds this checkout (Agentcard places a vault order itself when the approval lands): wait and read GET /buy/conversations/{id} instead of confirming again. Null on success and on recoverable errors.
The link to send the user when the attempt paused for their bank's or Vault's approval. Send the same confirm again once they approve.
Whether money moved on this call's checkout: none (nothing charged, nothing pending: every decline, approval pause and refusal answered before money moved), confirming (placed, charge still confirming), settled, or unknown (the attempt may have moved money and Agentcard cannot yet say; do not retry, read the conversation's orders, then support). Null when no checkout ran.
none, confirming, settled, unknown, null For a cart the merchant priced outside US dollars: the merchant's own total in that currency's smallest unit, the same figure order.placed and order.failed carry. Null for a US dollar cart and when no checkout ran.
The merchant's currency as a lower-case ISO code (cad) when the cart was priced outside US dollars. Null for a US dollar cart and when no checkout ran.
Asks that did not make it into a cart, cumulative for the conversation, with machine-derived reasons and the moment each happened. An entry leaves only when the same line later lands in a cart; placing an order does not clear it. Never inferred from the reply. Always an array.