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 areamazon.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 asmaxPriceCentswhen 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).
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.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.
shipToLabelslists the account’s saved US address labels, sorted, at most ten. A label past the first ten still works asplace_order’sshipTo.shipTois the label the order ships to by default: the address labelledship, or the only one saved, when that is a US address whose label is inshipToLabels. It isnullotherwise: 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 asplace_order’sshipTo. - When
shipToLabelsis 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. addressNotesays what to do in words.
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 asmaxPriceCents. 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 returninvalid_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.