Orders
Account scope required: include the X-Auth-Account header with your Account ID. List and view require the billing:read OAuth scope. Create, update and delete are not available via OAuth; they require a session or API-key credential.
Orders go through the cart and billing system. Each order is paid up front by the paying account's saved card, billed on a later invoice (post-pay), or invoiced for payment by bank transfer. See Checkout lanes.
POST /api/orders orders WordPress sites. POST /api/orders/domain registers or transfers a domain. Both always return a 202 cart envelope.
List all orders for an account
GET /api/orders
Params (optional)
- page: Integer | page number (default: 1)
- per_page: Integer | records per page (default: 50, max: 100)
Returned Params
- orders: Array
- id: String | uuid
- status: String
- created_at: DateTime
- updated_at: DateTime
- location: String | location short_name, or
nullfor orders with no location (e.g. domain-registration orders) - failure_reason: Object |
nullunless the registrar refused the order for a reason we explain; see Why a domain order failed- code: String
- message: String
- account: Object
- id: String
- name: String
View an Order
GET /api/orders/:id
Poll this endpoint until status reaches a terminal value (completed,
failed, cancelled).
Returned Params
- order: Object
- id: String | uuid
- status: String
- created_at: DateTime
- updated_at: DateTime
- location: String | location short_name, or
nullfor orders with no location (e.g. domain-registration orders) - failure_reason: Object |
nullunless the registrar refused the order for a reason we explain; see Why a domain order failed- code: String
- message: String
- tasks: Array
- id: Integer
- status: String
- site: Object | present when the order provisioned a site
- id: String
- name: String
- domain: String
- variant: String
- location: String
- ssh_data: Object |
nullwhen the site has no SFTP credentials- ipaddr: String
- username: String
- password: String
- port: Integer
- subscription: Object | present when the order has a backing subscription
- id: Integer | internal numeric id; not accepted by
/api/subscriptions/:id(see the note below) - status: String
- bucket_type: String
- bucket_year: Integer
- bucket_month: Integer
- stripe_id: String
- id: Integer | internal numeric id; not accepted by
- domain: Object | present when the order registered or transferred a domain
- name: String
- action: String |
registerortransfer - registration: Object | the domain registration record — see Domain Registration.
nullduring the async window, until the registrar call succeeds - provisioning_status: String | present only while
registrationisnull; mirrors the orderstatus
- payment: Object
- mode: String |
postpayfor an order billed on a later invoice (nothing was charged at checkout),upfrontfor every other order - status: String |
pending,processing,succeeded,awaiting_authentication,awaiting_bank_transfer,on_next_invoiceorfailed; see Payment status values - method_type: String | the payment method type (for example
cardorsepa_debit), ornull. Other values are possible; don't hard-code a list - invoice_date: Date | post-pay orders only: the date of the invoice that bills the order (
YYYY-MM-DD), then the invoice's own date - hosted_invoice_url: String | null — also
nullwhile a payment of that invoice is processing, so a customer does not pay it twice - amount_charged_cents: Integer | what the payment method paid.
nulluntil the invoice is available. For a post-pay order, this order's lines only (tax included, net of discounts) andnulluntil the invoice is paid - credit_applied_cents: Integer | customer balance the invoice consumed (never negative).
nulluntil the invoice is available, and alwaysnullfor a post-pay order - first_term_credit_cents: Integer | the first-term resize credit the invoice carries as a negative line, tax included, as a positive integer (
0when none).nulluntil the invoice is available. The invoice total is already net of it - method: String | bank-transfer orders only:
bank_transfer— with the other bank-transfer fields
- mode: String |
- account: Object | See accounts#show
- user: Object | See users#show
subscription.id is not the id /api/subscriptions/:id accepts
GET /api/subscriptions/:id takes the id returned by List Subscriptions, not this one, and returns 404 for it. List the account's subscriptions to find the one you need.
payment.status on order show and in the cart envelope use slightly different values. See Payment status values.
Why a domain order failed
When a domain registration or transfer fails because the registrar refused it for
a reason we can explain, the order carries failure_reason with a code and a
message. Unlike other error messages in the API, which are always English, message follows the request's Accept-Language header (English by default, Dutch for nl). In every other case, including a failed
order whose reason we do not explain, failure_reason is null: read status
to tell whether an order failed.
code |
Meaning |
|---|---|
invalid_authcode |
The transfer's authorization code is wrong. Get a new code from the current provider and place a new transfer order |
transfer_prohibited |
The domain has a transfer lock. Ask the current provider to remove it, then place a new transfer order |
invalid_contact |
The registry rejected the domain contact details. Correct them and place a new order |
already_registered |
A registration was refused because the domain is already registered |
nameserver_not_found |
One of the nameservers does not exist. Check them and place a new order |
Handle unknown code values, and show message to your user as it is.
Order a new Site
POST /api/orders
Charges the billing account's default payment method and provisions a WordPress site asynchronously. The endpoint always returns 202 Accepted with a polling envelope.
Location and plan names can be found by querying the /api/about endpoint.
The billing account must be ready to charge: a saved default payment method and a complete billing contact. Otherwise the response is 400 no_default_payment_method and no order is created. Externally invoiced accounts and workspaces billed by bank transfer don't need a saved payment method; see Checkout lanes.
Params
- site: Object (required)
- name: String | accepted but ignored; see the note below
- variant: String (required) | vanilla, extendify
- location: String (required) | Location short_name (e.g. "pdx")
- plan: String (required) | Product short_name (e.g. "basic")
- term: String (required) | monthly or annual
- callback: Object | optional outbound notification POSTed when the order's async task completes — see Callbacks
- authorization: String | full Authorization header value. Example:
Bearer 12345 - url: String | fully qualified URL
- authorization: String | full Authorization header value. Example:
You cannot name the site
The site is named after a domain ordered in the same request; otherwise it gets a generated name. Read the real name from the order once it has provisioned.
Returned Params (always 202 Accepted)
- status: String |
"accepted" - cart: Object
- token: String
- status: String |
active,processing,checked_out - rollup_status: String |
pending,processing,completed, ... - poll_url: String | absolute URL, e.g.
https://your-instance/api/carts/<token>
- payment: Object
- mode: String |
postpay— present only when the cart's orders are billed on a later invoice - status: String |
processing,succeeded,awaiting_authentication,awaiting_bank_transfer,on_next_invoice,pendingorfailed; see Payment status values - method_type: String | the payment method type (for example
cardorsepa_debit), ornull. Other values are possible; don't hard-code a list - invoice_date: Date | present only for a post-pay cart: the date of the invoice (
YYYY-MM-DD) - hosted_invoice_url: String | null
- method: String | bank-transfer orders only:
bank_transfer— with the other bank-transfer fields
- mode: String |
- orders: Array
- id: String | uuid
- status: String |
pending - poll_url: String | absolute URL, e.g.
https://your-instance/api/orders/<id>
- billing: Object | present only when the order was placed post-pay — see Post-pay orders
Poll cart.poll_url (or each order's poll_url) until the orders reach a terminal state. orders is empty at first; you get the order ID by polling the cart.
Errors
Every 4xx carries a machine-readable code alongside errors. Nothing is
charged and no order is created.
- 400
missing_account| theX-Auth-Accountheader is absent - 400
account_cannot_order| the account is not permitted to create orders - 400
unknown_variant|variantis not a known variant type - 400
unknown_location|locationis not a known public location - 400
over_capacity| the variant has no inventory at that location — retryable - 400
unknown_term|termis notmonthlyorannual - 400
unknown_product|planis not orderable on the account's billing plan - 400
no_price_for_plan| no price forplanat the requestedterm - 400
item_add_failed| the cart rejected the site item - 400
no_default_payment_method| billing account not ready to charge - 422
cart_pay_failed| the payment could not be started
Checkout-lane refusals (for example billing_permission_required, outstanding_balance_exceeded, recent_dispute) are listed under Checkout lanes and refusals.
Register or Transfer a Domain
POST /api/orders/domain
Registers or transfers a domain, charging the account's default payment method, then creates a renewal subscription and DNS zone. Always returns 202 Accepted with the shared cart envelope; poll /api/orders/:id (which carries a domain block) until status is terminal.
Requires a user-scoped credential (a system API key with no user returns 401 user_required) and the X-Auth-Account header. Returns 503 feature_disabled when domain registration isn't enabled, and 403 trial_account for trial accounts.
Params
- domain: Object (required)
- name: String (required) | fully-qualified, e.g.
example.com - action: String (optional) |
register(default) ortransfer - authcode: String | required for transfers when the TLD requires an authcode
- nameserver_mode: String (optional) |
default(our nameservers; also used when absent),keep(transfer only: keep the domain's current nameservers) orcustom - nameservers: Array | required with
nameserver_modecustomand refused otherwise: 2–4 hostnames, none inside the ordered domain.keepandcustomcreate no DNS zone, because the domain is hosted externally - contact: Object | inline registrant; required unless
contact_sourceis given- first_name: String | at least one of
first_nameandlast_nameis required; put a single-word name inlast_name - last_name: String | see
first_name - organization: String (optional)
- street_address: String (required)
- post_code: String (required)
- city: String (required)
- state: String (optional/required per TLD)
- country: String (required) | 2-letter ISO code
- email: String (required)
- phone: String (required) | E.164, e.g.
+1.5555555555 - extra_properties: Object | TLD-specific registry fields (e.g.
.itentityType)
- first_name: String | at least one of
- contact_source: Object | reuse an owned registration's contacts instead of
contact- registration_id: Integer (required) | an owned DomainRegistration that has an owner contact
- role_contacts: Object (optional) |
admin/billing/tech; each:- source: String |
same_as_owner(default),existing, ornew - source_registration_id: Integer | when
sourceisexisting - first_name, last_name, ... | the same contact fields as above, when
sourceisnew
- source: String |
- name: String (required) | fully-qualified, e.g.
- callback: Object (optional) | same callback contract as
POST /api/orders— see Callbacks- authorization: String | full Authorization header value. Example:
Bearer 12345 - url: String | fully qualified URL
- authorization: String | full Authorization header value. Example:
Provide the registrant with either an inline contact object or contact_source.registration_id (to reuse the contacts of an owned registration), not both.
Returned Params (always 202 Accepted)
Identical envelope to POST /api/orders:
- status: String |
"accepted" - cart: Object |
{ token, status, rollup_status, poll_url } - payment: Object |
{ status, method_type, hosted_invoice_url } - orders: Array |
[{ id, status, poll_url }](empty during the async window)
Errors
Authorization / gating:
- 401
user_required| system Account-bearer key (no user) - 503
feature_disabled| domain registration not enabled - 403
trial_account| trial accounts cannot order domains
Validation (400, no charge / no order created):
missing_account| theX-Auth-Accountheader is absentaccount_cannot_order| the account is not permitted to create ordersinvalid_action|actionnotregisterortransferinvalid_domain| name failed normalization/validationunsupported_tld| no configured TLD for the namepricing_unavailable| no orderable price for the account's billing planauthcode_required| transfer of a TLD that requires an authcode, none suppliedinvalid_nameservers| unknownnameserver_mode,keepon a registration, a badcustomlist, ornameserverssent withoutnameserver_modecustomincomplete_contact| inline contact missing required fields (including bothfirst_nameandlast_name)invalid_contact| inline contact has a bad value (e.g.countrynot 2 letters)invalid_contact_source|contact_source.registration_idnot found or has no owner contactno_default_payment_method| billing account not ready to charge
Checkout-lane refusals use the same codes as
POST /api/orders — see
Checkout lanes and refusals.
Processing (422):
domain_unavailable| registry says the name is not registerable (register only)domain_availability_unknown| the availability check failed, so it is unknown whether the name is registerable; retry (register only)domain_add_failed| cart rejected the domain (e.g. already owned)domain_contact_invalid| registrant contact rejected (body carriesviolations)domain_contact_needs_augmentation| TLD needs extra contact fields (body carriesneeds_augmentation)cart_pay_failed| the payment could not be started
domain_unavailable is not the same as domain_availability_unknown
Only domain_unavailable means the name can't be registered. On domain_availability_unknown, retry rather than telling the customer the name is taken.
Checkout lanes and refusals
Every paid endpoint that answers with the cart envelope (POST /api/orders, POST /api/orders/domain, domain registrations, and creating or resizing sites, cPanel accounts and mailspaces) pays in one of three ways: up front by card, post-pay on a later invoice, or by bank transfer. The lane is set per order from the paying account's billing state; you can't choose it in the request.
The 202 envelope and GET /api/orders/:id show which lane an order took:
| Lane | What the response shows |
|---|---|
| Post-pay | payment.mode: "postpay", payment.status on_next_invoice until the order is invoiced, and in the 202 envelope a billing object |
| Bank transfer | payment.method: "bank_transfer", payment.status awaiting_bank_transfer until the invoice is paid, and the transfer details |
| Up front | neither of the above |
GET /api/orders/:id and a domain holder change don't include billing; they show post-pay through payment.mode only.
Post-pay orders
On a post-pay success the usual envelope is returned with
payment.mode: "postpay" and payment.invoice_date, plus:
Returned Params (billing)
- billing: Object
- mode: String |
postpay - invoice_date: Date | the invoice that will bill the order (
YYYY-MM-DD) - entries: Array | the charges this cart adds, reversals left out. Amounts are tax-exclusive cents
- id: Integer
- workspace_id: String | the workspace's API
id - order_id: String | uuid, or
null - kind: String
- description: String
- amount_cents: Integer
- discount_cents: Integer
- tax_estimate_cents: Integer | an estimate; the invoice fixes the tax
- currency: String
- period_start: DateTime | or
null - period_end: DateTime | or
null - state: String
- mode: String |
Bank-transfer payment fields
For an order paid by bank transfer, the payment block of the cart envelope and of GET /api/orders/:id adds the following. The invoice fields are null until the invoice is available.
Returned Params (payment, bank transfer)
- payment: Object
- method: String |
bank_transfer - invoice_id: String | our invoice id
- invoice_number: String | also the transfer reference
- amount_due_cents: Integer | what is still owed
- currency: String | lowercase ISO code
- due_date: Date |
YYYY-MM-DD - instructions: Object |
nullonce the invoice is paid or void, and for a failed or canceled order- type: String |
eu_bank_transferorus_bank_transfer - reference: String
- account_holder_name: String |
eu_bank_transferonly - iban: String |
eu_bank_transferonly - bic: String |
eu_bank_transferonly - country: String |
eu_bank_transferonly - bank_name: String |
us_bank_transferonly - routing_number: String |
us_bank_transferonly - account_number: String |
us_bank_transferonly
- type: String |
- method: String |
If every order of a bank-transfer cart failed or was canceled, payment.status
is failed, instructions is null and no payment link is returned.
Payment status values
payment.status takes these values:
| Value | Meaning | Order show | Cart envelope |
|---|---|---|---|
pending |
Nothing has been paid yet | Yes | Post-pay carts only |
processing |
A payment is in progress | Yes | Yes. Also the status of any cart not yet checked out |
succeeded |
Fully paid | Yes | Yes, once the cart is checked out |
awaiting_authentication |
The bank requires the customer to confirm the payment. Send them to hosted_invoice_url |
Yes | Yes |
awaiting_bank_transfer |
A bank-transfer invoice is open with an amount still owed. succeeded once it is paid |
Yes | Yes |
on_next_invoice |
Post-pay order not yet invoiced (see invoice_date). After that, the invoice's own status |
Yes | Yes |
failed |
Declined, bounced or canceled. Also when every order of a bank-transfer cart failed or was canceled | Yes | Yes |
Order show derives the value for each order from that order's state; the cart envelope derives it for the whole cart. The two can differ at the same moment, so handle the status where you read it. For externally invoiced accounts the envelope stays processing and never reaches succeeded; watch for orders[].status completed instead.
If a direct debit bounces after the order was provisioned, the order stays completed but payment.status follows the invoice: failed with hosted_invoice_url set while it is owed, processing (no link) while a new payment is on its way, and succeeded once it is paid.
Refusal codes
A refused order returns errors and a machine-readable code; most codes add a
remediation string.
| Status | Code | Meaning and what to do |
|---|---|---|
| 409 | postpay_busy, bank_transfer_busy, sepa_checkout_busy |
Another order of the same payer is being placed. Retry in a few seconds |
| 422 | postpay_route_changed |
The lane changed while the order was placed. Retry the request |
| 422 | postpay_promo_invalid |
The cart's promotion code can no longer be used; reason says why. Remove the code and order again, or retry for reason: "unavailable" |
| 422 | postpay_pay_open_invoices |
The order cannot be placed until the paying account's open invoices are paid; reason says why it is blocked. invoices lists them, oldest first (id, number, amount_cents (the amount still owed), currency, due_date, pay_url), only for a user who can manage billing on the paying account. For anyone else, remediation asks for such a user |
| 422 | postpay_contact_support |
The order cannot be placed right now and only support can clear it; Contact support |
| 422 | postpay_payment_in_progress |
An earlier payment of the paying account is still being processed, or its payment method could not be checked. Retry in a few minutes |
| 422 | postpay_add_payment_method |
A resize or plan change on a paying account with no saved payment method. Add a default payment method, then try again |
| 403 | billing_permission_required |
The workspace pays by bank transfer and the user cannot manage billing on the paying account. Order as a user who can |
| 400 | billing_details_incomplete |
The paying account's billing contact has no address, city or country. Complete it, then order again |
| 422 | payer_in_dunning |
The paying account has an overdue invoice. Pay the open invoices, then order again |
| 422 | outstanding_balance_exceeded, in_flight_limit_exceeded |
The order would take what the payer owes over its limit. Pay the open invoices; support can raise the limit |
| 422 | instant_payment_method_required |
The order must be paid up front and the paying account's default is not a card. Make a card the default, or order in the dashboard and pay by card or iDEAL |
| 422 | sepa_not_trusted |
The order cannot be paid by direct debit yet. Make a card the default, or pay a first order by iDEAL or Bancontact |
| 422 | recent_dispute |
A returned payment or chargeback in the last 90 days. Make a card the default, or contact support |
| 422 | bank_transfer_refused |
The order cannot be invoiced for bank transfer. Contact support |
| 422 | postpay_change_refused, first_term_credit_blocked |
A resize or plan change that cannot go through right now. Contact support |
| 409 | bank_transfer_in_progress |
An earlier order of the payer never completed. Do not order again; contact support |
| 422 | bank_transfer_failed |
The order stopped after it was invoiced. Do not repeat the request — it would place a second order. Contact support |
| 422 | postpay_failed |
The order stopped part way. Check the account's orders before repeating the request, so it is not placed twice |
The four postpay_pay_open_invoices, postpay_contact_support, postpay_payment_in_progress and postpay_add_payment_method refusals place no order, so the request can be repeated once the cause is cleared. All four can carry reason.
The limit codes can add outstanding_cents, limit_cents, order_cents and
currency.
Cancel an Order
Cancels an in-progress order.
DELETE /api/orders/:id
Returns 202.
Errors
- 422
payment_processing| a direct debit for the order has not settled yet; the order cannot be canceled until it does
PATCH is a no-op
PATCH /api/orders/:id is reserved and returns 400.
Carts
Poll cart-level state during the async window after POST /api/orders, a site
plan change, or any other paid endpoint that
answers with the same cart envelope.
Account Scope Required (X-Auth-Account). Scope: billing:read. Carts are
scoped to your own account; an unknown token returns 404.
GET /api/carts/:token
The cart token comes from the create response (cart.token / cart.poll_url).
The response shape mirrors POST /api/orders so you can reuse the same parser:
Returned Params
- status: String |
"accepted" - cart: Object
- token: String
- status: String
- rollup_status: String
- poll_url: String
- payment: Object
- status: String
- method_type: String | the payment method type (for example
cardorsepa_debit), ornull. Other values are possible; don't hard-code a list - hosted_invoice_url: String | null
- orders: Array
- id: String | uuid
- status: String
- poll_url: String
The payment block also carries mode and invoice_date for a post-pay cart and
the bank-transfer fields for a bank-transfer
cart, exactly as on POST /api/orders.