> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# buy_checkout

> DESTRUCTIVE: place + pay for the current cart.

Connect to `https://mcp.agentcard.sh/mcp` with the **user's connection token** (or a `buy_token` for org-owned accounts).

**Behavior:** destructive.

<Note>Not in the default `tools/list`. It is still callable by exact name, and appears when the client sends the `x-expert-tools: 1` header.</Note>

## What it does

DESTRUCTIVE: place + pay for the current cart. Runs the spend gate, creates a one-time card sized to the cart total, presents it at the merchant, and places the order. Confirm the cart total with the user first. Returns needs\_approval if a spend approval is required. May also return denied with an account gate — kyc\_required (run start\_kyc), user\_info\_required (run submit\_user\_info), insufficient\_balance (run add\_funds) — each reply names the tool to run before retrying with the same idempotency\_key. To make retries SAFE (e.g. after a timeout), pass the SAME idempotency\_key on every retry of one purchase — the backend then reuses the single reservation/card instead of charging twice. Use a fresh key only for a genuinely new purchase.

## Inputs

| Field | Type | Description |
| - | - | - |
| `merchant` *(required)* | string | |
| `expected_total_cents` | number | the FINAL total in cents you showed the user and they confirmed — cart total PLUS any tip\_cents you pass. The server re-reads the live cart and rejects the checkout (409 cart\_total\_changed) if it no longer adds up, so an amount the user never saw can never be charged. Always pass it when you showed a total. |
| `expected_address_id` | string | the id (from buy\_addresses / the one you passed to buy\_set\_default\_address) of the delivery address the user confirmed. The server re-asserts it as the merchant default and rejects the checkout (409 address\_changed) if it can't, so the order can never ship to a stale/other address. Always pass it once a delivery address is set. |
| `tip_cents` | number | optional Dasher tip in cents; added to the charge and the created card size |
| `delivery_time` | string | optional ISO-8601 time to SCHEDULE delivery for (e.g. "2026-06-17T23:00:00Z"); omit for ASAP |
| `approval_id` | string | a previously-issued spend approval id, if checkout returned needs\_approval |
| `idempotency_key` | string | a stable key for this purchase; reuse it on every retry so a timed-out/retried call never double-charges |
| `cart_rebuilt` | boolean | pass true ONLY after a pos\_cart\_validation rejection AND after you actually re-added the item with corrected option selections — it overrides the server's block on re-checking-out a cart it saw the restaurant's register reject. Never pass it on a cart you haven't changed. |

## Returns

None.

## Example call

```json theme={null}
{
  "tool": "buy_checkout",
  "arguments": {
    "merchant": "\u2026"
  }
}
```


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