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

# Quick checkout

> Let your agent buy from supported retailers without a browser: search, quote, place the order, then follow it, while the account holder approves every order that passes the card's controls.

Quick checkout lets your agent buy from a set of large retailers without opening
a page or filling a checkout. The agent searches, prices the product, and places
the order. Agent Vault buys it and charges the card. This guide walks the flow
end to end.

> [!WARNING]
>
> **Quick checkout is a preview and is not yet generally available.** Its tools are
> listed only for an account Agent Vault has turned it on for
> (`capabilities.quickCheckout` in the [token catalog](https://docs.agentvault.io/reference/token-catalog.md)).
> For any other account the MCP tools `search_products`, `quote_order` and
> `place_order` are not listed at all, and their HTTP endpoints answer
> `quick_checkout_unavailable` for anything new. Resending a `place_order` with the
> same body and idempotency key still answers the order it already made, so an
> order whose answer was lost can be recovered. An account it was turned off for keeps `get_order`
> and `cancel_order` for any order already in flight, so an order can still be
> followed, and cancelled while `cancel_order` still allows it. Do not build a
> production flow on it yet.

## What it is

Some sites block the vault's browser, or are better bought from without it. On
the Quick checkout retailers, the agent does not drive the page. Agent Vault
places the order and charges the account's card, so the statement shows Agent
Vault, not the retailer.

The retailers today are `amazon.com`, `walmart.com`, `bestbuy.com`, `target.com`,
`homedepot.com` and `lowes.com`.

The same controls as a card fill apply, and **the account holder approves every
order that passes them, the first one included**. An order a paused card or
the card's merchant rules refuse ends `blocked` without asking anyone.
If the card has not been set up for Quick checkout yet, the first order on it also asks them to confirm it once. If the
account has not approved the retailer yet (on **Destinations**, through a saved
login, or in the merchant list of an active agent card that allows only listed
merchants), the first order there also asks
them to approve that store. Spending and plan limits are checked after that
approval, so an order over a limit at a new retailer asks for the store first
and then ends `blocked`. A card or retailer already set up raises neither
prompt.

## When to use it

Use Quick checkout for these retailers. Use the [browser checkout](https://docs.agentvault.io/guides/first-checkout.md)
for every other site. With Quick checkout on, `open_page` on a Quick checkout
site does not open a browser. A search or product URL it recognizes answers with
search results or product data and points you to the tools below. Any other page
on those sites, such as the homepage, a cart or a category page, answers
`status=unsupported code=quick_checkout_host next=search_products`: search with
`search_products` instead. With it off, those sites open like any other.

## The flow

The flow is search, quote, place, then follow.

**1. Search for the product**

Call [`search_products`](https://docs.agentvault.io/mcp/tool-reference#search_products) with what the user
asked for, and set `retailer` when they named a store. Each result carries a
`productUrl`. Skip this step if the user gave you the product page URL.

On Amazon and Walmart, when the title does not settle the size, colour or pack
the user wants, call `open_page` on the `productUrl` to list the variants and
quote the one they want. When a variant comes back with only its `productUrl`
and no size, colour or pack named, open that URL too, and quote it only once its
`selectedVariant` or details match what the user asked for. Amazon results do not even say whether a product has
variants, so check when in doubt.

**2. Quote it**

Call [`quote_order`](https://docs.agentvault.io/mcp/tool-reference#quote_order) with the product URL (the
variant's URL, once you have settled it) and, when the user wants more than one,
the `quantity`; it defaults to 1. A quote with a price returns:

* `suggestedMaxPriceCents`, the price plus headroom for tax and shipping. Pass it
  as `maxPriceCents` when you place the order.
* `maxHoldCents`, the figure the account holder approves: the hold the order is
  meant to stay within, order and card fees included. If the retailer secures
  more after placing has started, the account holder is notified of the actual
  amount.
* `chargeNote`, the same in words. Tell the user what their card can be charged,
  not only the item price.
* Where the order ships (see [below](#where-the-order-ships)).

A quote with `priceCents: null` has no `suggestedMaxPriceCents`, `maxHoldCents`
or `chargeNote`: ask the user for the most they will pay the store, items, tax
and shipping together, and pass that as `maxPriceCents`. The hold the account
holder approves adds the order and card fees on top, so tell the user the charge
can be higher than that (see [Listed-price retailers](#listed-price-retailers)).

**3. Place the order**

Call [`place_order`](https://docs.agentvault.io/mcp/tool-reference#place_order) with the quote's
`suggestedMaxPriceCents` as `maxPriceCents`, or the user's ceiling for a quote
with `priceCents: null`, and the card's number token. Pass
the same `quantity` you quoted in that product's `products` entry; it also
defaults to 1. It
answers at once with the order id. The order does not go to the retailer until
the account holder approves it.

**4. Follow it**

Call [`get_order`](https://docs.agentvault.io/mcp/tool-reference#get_order) with that id while the order
waits on the owner (`waiting_on_owner=true`): tell the user, then keep calling in
the same turn with `waitSeconds: 15`, so each call waits for a change instead of
answering at once. Once it is being placed (`next=tell_user`), tell the user the
account holder will be notified in Agent Vault when it is placed or if it fails,
and **stop polling**. Placing usually takes 10 to 15 minutes and
can take longer. Call `get_order` again later only if they ask.

The HTTP equivalents follow the same order: `POST /v1/products/search` and
`POST /v1/products/details` for the search and variant lookup, then
`POST /v1/orders/quote`, `POST /v1/orders`, `GET /v1/orders/{id}` and
`POST /v1/orders/{id}/cancel`. See the
[HTTP API](https://docs.agentvault.io/reference/http-api.md#quick-checkout-orders).

## Where the order ships

Every quote says where the order would ship, so you can tell the user before you
place it. An order can be cancelled while it waits on the account holder
(`created` or an `awaiting_` state), and once it is `submitted` until the
retailer starts on it. While it is `submitting` or `submit_uncertain`, and once
the retailer has started, `cancel_order` refuses with `order_not_cancellable`.

* `shipToLabels` lists the account's saved US address labels, sorted, at most
  ten. A label past the first ten still works as `place_order`'s `shipTo`.
* `shipTo` is the label the order ships to by default: the address labelled
  `ship`, or the only one saved, when that is a US address whose label is in
  `shipToLabels`. It is `null` otherwise: when there is no US default, even if a
  non-US address is the only one saved, or when the default's label falls past
  the first ten.
* When the quote's status line is `next=ask_user`, the account has more than one
  US address, or the default is not a US address. Ask the user which address,
  unless they already said, and pass that label as `place_order`'s `shipTo`.
* When `shipToLabels` is empty, the account has no US address Quick checkout
  can use: none is saved, or a saved one has a label it cannot use. Do not place
  the order: ask the user to have the account holder add a US address, or
  relabel the one they have, in Agent Vault, then quote again.
* `addressNote` says what to do in words.

Quick checkout ships to US addresses only for now. An order to a non-US address
is refused with `unsupported_country`, which lists the US labels to ask about.

## Listed-price retailers

Target, Home Depot and Lowe's have no confirmed product data through Quick
checkout, and Best Buy uses a listed price when its data is unavailable. For
these stores:

* The price comes from search and can lag the store's page. Results carry
  `priceSource: "listed"`.
* The quote adds headroom for tax and for the lag, plus a shipping allowance
  unless search listed free shipping for the product. If
  the store's real total, shipping included, is above `maxPriceCents`, the order
  fails and nothing is charged.
* There is no size, colour or pack data. If the title does not settle the variant
  the user wants, confirm it before you quote.
* A listed price is kept for 30 minutes after the search. A product URL the user
  pasted, with no listed price, gets a quote with `priceCents: null`: ask the
  user for the most they will pay the store, and pass it as `maxPriceCents`.
  The fees come on top of it.

## When the account holder approves

Agent Vault turns Quick checkout on for an account. Once it is on, the owner
manages it on the dashboard: the **Quick checkout** page under **Workspace** sets
up cards for it ahead of time, and shows orders waiting for approval and the one-time
card confirmation. Setting up a card there is not a limit on which cards may be
used: an order on any other card asks the account holder to confirm that card
during its first approval. Approvals and the order notifications work like every other
hold. See [Approvals and notifications](https://docs.agentvault.io/dashboard/approvals-and-notifications.md).

## Errors

Each endpoint's own errors are in the Errors table under
[Quick checkout orders](https://docs.agentvault.io/reference/http-api.md#quick-checkout-orders) in the HTTP
API: search can return `invalid_retailer`, placing an order can return
`token_not_found` or `card_blocked`, and more. What becomes of an order, and
whether retrying is safe, is on
[Quick checkout orders](https://docs.agentvault.io/sdk/error-codes.md#quick-checkout-orders) in the error
codes. A control that refuses an order comes back as a
`blocked` order with the card fill code as its reason, such as `limit_reached` or
`merchant_blocked`. Over HTTP and the SDK that is the order itself, not a failed
request. Over MCP, `get_order` answers `status=error` with that code and marks the
call as an error. Either way, tell the user, and do not place the same order
again on your own: a blocked order is final. Whether a new order can work
follows that code's retry rule in
[Spending, limits and approval](https://docs.agentvault.io/sdk/error-codes.md#spending-limits-and-approval)
or [Card and merchant refusals](https://docs.agentvault.io/sdk/error-codes.md#card-and-merchant-refusals). Some, such as
`card_paused`, can once the account holder resumes the card. After
`limit_reached`, a new order can work once the limit resets or is raised; if the
card paused itself at the limit, the account holder must also resume it. `quick_checkout_unavailable` means Quick checkout was not
available when the order was placed: nothing was charged, and a new order may
work later if the user still wants it.

## Next steps

> [card] [Tool reference](https://docs.agentvault.io/mcp/tool-reference.md#quick-checkout-preview)
>
> The five Quick checkout tools and what they return.

> [card] [HTTP API](https://docs.agentvault.io/reference/http-api.md#quick-checkout-orders)
>
> The order endpoints, for use without the SDK.

> [card] [Error codes](https://docs.agentvault.io/sdk/error-codes.md#quick-checkout-orders)
>
> Every order refusal and whether to retry.

> [card] [Confirming outcomes](https://docs.agentvault.io/guides/confirming-outcomes.md)
>
> What counts as proof an order went through.


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