Orders/create_checkout
Tool · Orders

create_checkout

Create a checkout: validate and quote a list of items — hosting plans and other products (pid, billing_cycle and the option, custom-field and add-on ids from get_hosting_plan), domain registrations (domain, years) and domain transfers (domain; a transfer needs no EPP code here — never request one) — for the customer's own account, and return the checkout object. Prices come ONLY from the checkout: never compute, sum, convert or guess a price. Show the customer every item with its today price, recurring price and renewal, and totals.today, all in the checkout's currency exactly as returned. status "ready" means it can be completed; "incomplete" means at least one items[].checks entry is ok:false or a message needs input — needs_input messages name the field to supply (for example a required custom field or a TLD field under domain_fields); fix it with update_checkout. Premium domain names are quoted at their premium price (items[].premium.is_premium with its own renewal) and are re-checked when completing: a changed price returns price_changed with the new quote, so show it and ask again. A premium name may instead be refused with the item check premium_not_supported (for example while the account holds credit): do not retry, tell the customer the message and offer the website cart or a ticket. Server products (get_hosting_plan reports server_fields_required) need hostname, ns1prefix and ns2prefix on their item and should NOT be given a rootpw: a strong password is generated and delivered by the welcome email; the checkout only reports server.rootpw_set. account_id is only needed when the connection may order for several accounts (an account_required message lists them). Then complete_checkout. Requires the ordering permission (prepare orders) the customer granted.

Open‑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 #

itemsarray<object>Required
The items to order (at most 10 domain items). Each item is a product, a domain_register or a domain_transfer.
typestring
"product" (a hosting plan or other product from get_hosting_plan), "domain_register" (register a new domain) or "domain_transfer" (transfer an existing one in).
One of: product domain_register domain_transfer
pidinteger
Product items only: the product id from list_hosting_plans / get_hosting_plan.
billing_cyclestring
Product items only: one of the product's allowed_cycles from get_hosting_plan, spelled exactly.
config_optionsobject · array
Product items only: { "<config option id>": <sub option id or quantity> } using the ids from get_hosting_plan. Omit it, or pass {}, when the product has none.
custom_fieldsobject · array
Product items only: { "<custom field id>": "<value>" } using the ids from get_hosting_plan; a required field left out comes back as a needs_input message.
addonsarray<integer>
Product items only: add-on ids from get_hosting_plan.
domainstring
Product items: the hosting domain (when the product requires_domain). Domain items: the domain name to register or transfer.
yearsinteger
domain_register only: the registration period in years (premium names: 1).
domain_fieldsobject · array
Domain items only: { "<TLD field name>": "<value>" } for TLDs that require extra registrant details; a needs_input message names the field and its options.
hostnamestring
Server products only; required when the product's server_fields_required is true: the server's host name (for example srv1.example.com).
ns1prefixstring
Server products only; required when the product's server_fields_required is true: the first nameserver prefix (for example ns1).
ns2prefixstring
Server products only; required when the product's server_fields_required is true: the second nameserver prefix (for example ns2).
rootpwstring
Server products only; OPTIONAL — prefer omitting it: a strong password is generated and delivered by the welcome email; never ask the customer to dictate a password in chat; it is never returned; 8–64 characters from letters, digits and !@#%^*_=+.:,- if you must supply one.
promo_codestringOptional
A promo code to apply to the whole checkout. The quote reports promo_invalid when it does not apply.
account_idintegerOptional
The account to order for; only when the connection may order for several accounts (an account_required message lists the options). Omit it otherwise.

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": "invalid_params" }See the tool description for when this result is returned.
{ "error": "backend_unavailable" }See the tool description for when this result is returned.
{ "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": "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": "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": "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": "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.