Orders/complete_checkout
Tool · Orders

complete_checkout

Complete a ready checkout and return the checkout object. BEFORE calling: show the customer every item and totals.today in the checkout's currency exactly as returned (never compute prices), get their explicit agreement, then pass confirm:true — without it the tool answers confirm_required and nothing happens. mode "link" (the default) returns continue_url: give it to the customer to open, log in and click "Order and pay" in the client area; the checkout becomes requires_escalation. mode "pay" charges the customer's stored card and places the order at once; it REQUIRES idempotency_key (8–64 characters of letters, digits, _ . : -; make one up per attempt and reuse the SAME key when retrying that attempt — optional for link). Read the result's status and messages: requires_escalation — hand continue_url over, the customer finishes in the browser; completed — the order is placed (order.status "Paid", or "none" for a free order); a message payment_declined or requires_3ds — the order was cancelled and nothing was charged, give the customer continue_url to pay in the browser; paymethod_required (needs_input) — the customer has several saved cards: ask which one (payment_methods lists them) and repeat with paymethod_id and the same idempotency_key (with a single saved card, AI ordering set to "ask" charges it without this step); an info message such as ai_ordering_off or no_stored_card — pay was not possible and a link was issued instead. error="pay_not_permitted" means this connection lacks pay authority: use mode "link". error="checkout_not_ready" returns the checkout with what is wrong (a price_changed message means a new price: show it and ask again); error="idempotency_conflict" means the key belongs to another checkout. Requires the ordering permission (prepare orders) the customer granted; mode "pay" also needs the stored-card payment permission.

DestructiveOpen‑worldscope write:orders

Invoked over the MCP transport with a tools/call request naming this tool.

Authorization #

Requires a valid OAuth 2.1 bearer access_token whose grant includes the write:orders scope — Prepare orders (hosting, domains) for you to confirm and pay in the client area. The broker resolves the caller from the token and returns only records the account owns.

Parameters #

checkout_idstringRequired
The checkout id returned by create_checkout.
modestringOptional
"link" (default): a continue_url for the customer to pay in the client area. "pay": charge the stored card now (needs pay authority and AI ordering enabled by the customer).
One of: link pay
paymethod_idintegerOptional
The stored card to charge (from list_payment_methods or a paymethod_required message). Only with mode "pay"; omit it to let the customer's setting choose.
idempotency_keystringOptional
Required for mode "pay", optional for "link": a key you make up per attempt and reuse on a retry of the same attempt, so a repeated call never places a second order.
confirmbooleanRequired
Set true only after the customer explicitly agreed to the items and totals.today you showed them.

Response #

200 · application/json

idstring
statusstring
One of: incomplete ready requires_escalation completed expired canceled
itemsarray<object>
refstring
typestring
One of: product domain_register domain_transfer
descriptionstring
todaystring
recurringobject
cyclestring
amountstring
renewalstring
premiumobject
is_premiumboolean
renewalstring
serverobject
hostnamestring
ns1prefixstring
ns2prefixstring
rootpw_setboolean
checksarray<object>
codestring
okboolean
messagestring
needs_inputboolean
fieldstring
optionsarray<integer · string>
totalsobject
subtotalstring
discountstring
taxstring
todaystring
currencystring
messagesarray<object>
codestring
severitystring
One of: error needs_input info
fieldstring
textstring
optionsarray<integer · string>
continue_urlstring
expires_atstring
orderobject
order_idinteger
invoice_idinteger
statusstring
One of: Paid Unpaid Cancelled none
payment_methodsarray<object>
idinteger
typestring
brandstring
last4string
expirystring · null
is_defaultboolean
is_expiredboolean
messagestring
paramstring
scopestring
retry_after_secondsinteger

Errors #

ResultWhen
{ "error": "not_found" }The requested item does not exist, or it belongs to another account. Cross-account IDs are indistinguishable from missing ones by design.
{ "error": "invalid_params" }See the tool description for when this result is returned.
{ "error": "confirm_required" }The call changes something (places an order, runs a mutating operation) and was made without confirm:true. Show the customer what will happen, get their agreement, then repeat with confirm:true.
{ "error": "pay_not_permitted" }The connection may prepare orders but not pay with the stored card (the pay permission was not granted, or the credential lacks it). Complete with mode "link" and hand over continue_url.
{ "error": "backend_unavailable" }See the tool description for when this result is returned.
{ "error": "checkout_expired" }The checkout passed its expiry time; create a new one — it is quoted afresh.
{ "error": "checkout_not_ready" }The checkout has a failing item check, needs input, or its price changed since it was quoted. The checkout object comes back with the error; fix it with update_checkout (a re-quote clears price_changed), then complete it.
{ "error": "checkout_closed" }The checkout is already completed or canceled; nothing can be changed. Create a new checkout for a new order.
{ "error": "checkout_in_progress" }The checkout is being completed right now (a parallel request or the customer in the client area). Wait, then get_checkout shows the outcome.
{ "error": "idempotency_conflict" }The idempotency_key was already used for a different checkout. Use a new key, or the key that belongs to this checkout to retry it.
{ "error": "insufficient_scope" }The connection does not include the ordering permission; the customer can reconnect and grant it.
{ "error": "ordering_unavailable" }Ordering through the assistant is switched off (feature switch). The customer orders on the website or through a ticket.
{ "error": "rate_limited" }Too many requests of this kind in a short time; retry_after_seconds says how long to wait. Do not loop.
{ "error": "internal_error" }See the tool description for when this result is returned.