Skip to content

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 null for orders with no location (e.g. domain-registration orders)
    • failure_reason: Object | null unless 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 null for orders with no location (e.g. domain-registration orders)
    • failure_reason: Object | null unless 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 | null when 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
  • domain: Object | present when the order registered or transferred a domain
    • name: String
    • action: String | register or transfer
    • registration: Object | the domain registration record — see Domain Registration. null during the async window, until the registrar call succeeds
    • provisioning_status: String | present only while registration is null; mirrors the order status
  • payment: Object
    • mode: String | postpay for an order billed on a later invoice (nothing was charged at checkout), upfront for every other order
    • status: String | pending, processing, succeeded, awaiting_authentication, awaiting_bank_transfer, on_next_invoice or failed; see Payment status values
    • method_type: String | the payment method type (for example card or sepa_debit), or null. 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 null while a payment of that invoice is processing, so a customer does not pay it twice
    • amount_charged_cents: Integer | what the payment method paid. null until the invoice is available. For a post-pay order, this order's lines only (tax included, net of discounts) and null until the invoice is paid
    • credit_applied_cents: Integer | customer balance the invoice consumed (never negative). null until the invoice is available, and always null for 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 (0 when none). null until 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
  • 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

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, pending or failed; see Payment status values
    • method_type: String | the payment method type (for example card or sepa_debit), or null. 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
  • 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 | the X-Auth-Account header is absent
  • 400 account_cannot_order | the account is not permitted to create orders
  • 400 unknown_variant | variant is not a known variant type
  • 400 unknown_location | location is not a known public location
  • 400 over_capacity | the variant has no inventory at that location — retryable
  • 400 unknown_term | term is not monthly or annual
  • 400 unknown_product | plan is not orderable on the account's billing plan
  • 400 no_price_for_plan | no price for plan at the requested term
  • 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) or transfer
    • 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) or custom
    • nameservers: Array | required with nameserver_mode custom and refused otherwise: 2–4 hostnames, none inside the ordered domain. keep and custom create no DNS zone, because the domain is hosted externally
    • contact: Object | inline registrant; required unless contact_source is given
      • first_name: String | at least one of first_name and last_name is required; put a single-word name in last_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. .it entityType)
    • 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, or new
      • source_registration_id: Integer | when source is existing
      • first_name, last_name, ... | the same contact fields as above, when source is new
  • 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

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 | the X-Auth-Account header is absent
  • account_cannot_order | the account is not permitted to create orders
  • invalid_action | action not register or transfer
  • invalid_domain | name failed normalization/validation
  • unsupported_tld | no configured TLD for the name
  • pricing_unavailable | no orderable price for the account's billing plan
  • authcode_required | transfer of a TLD that requires an authcode, none supplied
  • invalid_nameservers | unknown nameserver_mode, keep on a registration, a bad custom list, or nameservers sent without nameserver_mode custom
  • incomplete_contact | inline contact missing required fields (including both first_name and last_name)
  • invalid_contact | inline contact has a bad value (e.g. country not 2 letters)
  • invalid_contact_source | contact_source.registration_id not found or has no owner contact
  • no_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 carries violations)
  • domain_contact_needs_augmentation | TLD needs extra contact fields (body carries needs_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

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 | null once the invoice is paid or void, and for a failed or canceled order
      • type: String | eu_bank_transfer or us_bank_transfer
      • reference: String
      • account_holder_name: String | eu_bank_transfer only
      • iban: String | eu_bank_transfer only
      • bic: String | eu_bank_transfer only
      • country: String | eu_bank_transfer only
      • bank_name: String | us_bank_transfer only
      • routing_number: String | us_bank_transfer only
      • account_number: String | us_bank_transfer only

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 card or sepa_debit), or null. 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.