Skip to main content
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.
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). 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 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 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 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).
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).
3

Place the order

Call 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 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.

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.

Errors

Each endpoint’s own errors are in the Errors table under 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 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 or 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

Tool reference

The five Quick checkout tools and what they return.

HTTP API

The order endpoints, for use without the SDK.

Error codes

Every order refusal and whether to retry.

Confirming outcomes

What counts as proof an order went through.