Create order

POST /api/v2/orders

Create an order using public product slugs, public IDs, and customer-facing fields.

Send a caller-generated attemptKey for retry-safe order creation: generate a fresh value per logical checkout/order attempt, then reuse the same value only when retrying that same request after a timeout or lost response.

Repeats with the same key can return the existing order/invoice for the previous attempt within the duplicate-prevention window (currently one hour).

Authentication is optional for signup checkout orders; anonymous callers must provide the required clientData.

Authenticated API callers normally omit clientData; the server uses the stored account profile.

Use the write:orders scope for least-privilege API keys; broader write:billing, write:services, and write:all keys remain compatible.

transfer:domains is for outgoing transfer/EPP-code actions and is not sufficient by itself to place a transfer-in order.

Use clientData only to override or provide missing account/profile fields.

Use item-level registrantContact when a domain should be registered to a different person or organisation than the account owner.

For regular fixed-cycle VPS orders, first call GET /api/v2/products/vps and send one of its data[].slug values as items[].productSlug; do not use this endpoint for pay-as-you-go Cloud VPS creation.

VPS customHostname and customHostnames values must be DNS-safe: letters, numbers, hyphens, and dots only, with each label starting and ending in a letter or number; underscores are not allowed.

To restore an existing VPS backup into a new regular VPS, add items[].restoreFromBackup with the source VPS public ID and backup public ID plus one target hostname through customHostname or a single-entry customHostnames array; the restore starts after the ordered VPS is provisioned.

PAYG Cloud VPS deployment uses POST /api/v2/vps/payg/deployments.

For shared hosting orders, first call GET /api/v2/products/shared-hosting, send one of its data[].slug values as items[].productSlug, and set items[].primaryDomain to the domain the hosting account should use.

For domain registration, first call GET /api/v2/products/domains/{tld} and GET /api/v2/domains/availability?name=example.se; copy required item-level values such as acceptedTerms, eppCode, premium, requiresRegistrarFeeAcceptance, nameservers, or copyExistingDns into the order item.

When copyExistingDns is true, copyExistingDnsScope can limit transfer-time DNS copying to all, website, or email; a shared-hosting item for the same domain uses its mxPreferences.dnsSetupPreference as the stronger source of intent.

If the caller's stored profile is missing a registry-required field, either update PATCH /api/v2/me before ordering or include a partial clientData override.

Payable orders return an invoice reference and may include a checkout URL.

Payment preferences are checkout hints for the invoice created by the order.

Use card, swish, bankgiro, sepa, or invoice when no specific payment flow should start.

Account credit is applied after invoice creation through the invoice credit action.

Billing & Orders Orders

Authentication

Required API scope: write:orders

Authenticate with an API key in the Authorization: Bearer <token> header.

Context

Headers

Authorization Bearer <token>
Accept application/json
Content-Type application/json

Body

required
application/json
items array<any>
clientData object

Optional for authenticated API-key/session orders. Use only to override or provide missing profile fields returned by availability/validation requirements. Required for unauthenticated signup orders.

clientData.firstName string · Example: Anna
clientData.lastName string · Example: Svensson
clientData.companyName string · Example: Example AB
clientData.email string · Example: user@example.com
clientData.address object
clientData.address.street string · Example: Examplegatan 1
clientData.address.address2 string · nullable · Example: null

Nullable: may be null when not applicable.

clientData.address.city string · Example: Stockholm
clientData.address.state string · Example: Stockholm
clientData.address.postalCode string · Example: 12345
clientData.countryCode string · Example: SE
clientData.phoneNumber string · Example: +46700000000
clientData.registrationIdentifier object
clientData.registrationIdentifier.value string · Example: 850507-3412
clientData.registrationIdentifier.countryCode string · nullable · Example: SE

Nullable: may be null when not applicable.

clientData.vatNumber string · Example: SE559999999901
clientData.accountType string · enum · Example: private
private
organisation
paymentMethod string · enum · Example: card

Canonical checkout preference for the invoice created by the order. Use card for card-backed hosted checkout flows, swish for Swish, bankgiro for Swedish SEK invoice payment, sepa for EUR SEPA bank transfer, or invoice to create the invoice without starting a specific payment flow. Provider names are not public v2 method values. Account credit is applied after invoice creation through the invoice credit action.

card
swish
bankgiro
sepa
invoice
attemptKey string · Example: order_attempt_01hxa3b4c5d6e7f8g9h0j1k2m3

Optional caller-generated idempotency key for retry-safe order creation. Generate a fresh value for each logical order/checkout attempt and reuse that exact value only when retrying the same request after a timeout or lost response. If the previous attempt created an order, repeats with the same key within the duplicate-prevention window (currently one hour) return that existing order/invoice instead of creating another order. Do not reuse a key for a different cart.

Responses

200 Idempotent retry returned the existing order or account-only result.
Order
id string required · Example: ord_01hxa3b4c5d6e7f8g9h0j1k2m3
number string required · Example: O-HXA3B4C5
status string · enum required · Example: pending
pending
active
completed
cancelled
failed
type string · enum · Example: new
new
renew
upgrade
transfer
invoiceId string · nullable required · Example: inv_01hxa3b4c5d6e7f8g9h0j1k2m3

checkoutUrl string · nullable · Example: https://cloud.hostup.se/billing?invoice=202600001

Compatibility alias used by older clients. New integrations should read invoice.paymentUrl when invoice is present.

client object
client.id string · nullable · Example: null

Nullable: may be null when not applicable.

client.email string · nullable · Example: user@example.com

Nullable: may be null when not applicable.

client.firstName string · nullable · Example: Anna

Nullable: may be null when not applicable.

client.lastName string · nullable · Example: Svensson

Nullable: may be null when not applicable.

client.companyName string · nullable · Example: null

Nullable: may be null when not applicable.

billing object required
billing.amount number · nullable required · Example: 199

Recurring fixed-cycle amount in the resource currency. Null when no fixed recurring amount applies, such as PAYG Cloud VPS billing.

billing.currencyCode string required · Example: SEK
billing.billingCycle string · nullable · enum required · Example: annually

Canonical billing cycle. VPS services with isPayg: true still report monthly for summary display; use isPayg to distinguish PAYG Cloud VPS from fixed-cycle VPS.

monthly
quarterly
semiannually
annually
biennially
triennially
free
billing.isPayg boolean required · Example: false

For VPS service/order billing, true means pay-as-you-go Cloud VPS and false means fixed-cycle/prepaid VPS. Non-VPS resources normally return false.

billing.periodYears integer · nullable · Example: 1

Nullable: may be null when not applicable.

invoice object | null
invoice.id string required · Example: inv_01hxa3b4c5d6e7f8g9h0j1k2m3
invoice.number string · nullable required · Example: 202600001

Nullable: may be null when not applicable.

invoice.amount number required · Example: 159
invoice.currencyCode string required · Example: SEK
invoice.dueAt string · nullable required · Example: 2026-05-11T23:59:59.000Z

Nullable: may be null when not applicable.

invoice.status string · enum required · Example: unpaid
paid
unpaid
partially_paid
draft
cancelled
refunded
invoice.paymentUrl string · nullable required · Example: /billing?invoice=202600001

Nullable: may be null when not applicable.

invoice.totals object required
invoice.dates object required
paymentStatus object
paymentStatus.status string · enum · Example: unpaid
paid
unpaid
credit_note
pending
unknown
paymentStatus.reason string · nullable · Example: Invoice is unpaid.

Nullable: may be null when not applicable.

actions object required
actions.canRetry object
actions.canRetry.allowed boolean required · Example: true
actions.canRetry.reason string · nullable required · Example: null

Nullable: may be null when not applicable.

actions.canRetry.code string · nullable · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canCancel object
actions.canCancel.allowed boolean required
actions.canCancel.reason string · nullable required

Nullable: may be null when not applicable.

domains array<object>
hosting array<object>
addons array<object>
upgrades array<object>
invoiceLookupPending boolean · Example: false
restoreIntents object

Present when a regular VPS order should restore an existing backup after provisioning. dispatchDeferred: true means the durable restore intent was stored and will be retried from the account-created webhook.

restoreIntents.requested integer · Example: 1
restoreIntents.created integer · Example: 1
restoreIntents.queued integer · Example: 1
restoreIntents.skipped integer · Example: 0
restoreIntents.dispatchDeferred boolean · Example: false
createdAt string · nullable

contractAcceptedAt string · nullable · Example: null

notes string · nullable · Example: null

referenceNumber string · nullable · Example: null

Variant 2

No fields

201 Order created.
id string · Example: ord_01hxa3b4c5d6e7f8g9h0j1k2m3
number string · Example: O-HXA3B4C5
status string · enum · Example: pending
pending
active
completed
cancelled
failed
type string · enum · Example: new
new
renew
upgrade
transfer
invoiceId string · nullable · Example: inv_01hxa3b4c5d6e7f8g9h0j1k2m3

checkoutUrl string · nullable · Example: https://cloud.hostup.se/billing?invoice=202600001

Compatibility alias used by older clients. New integrations should read invoice.paymentUrl when invoice is present.

client object
client.id string · nullable · Example: null

Nullable: may be null when not applicable.

client.email string · nullable · Example: user@example.com

Nullable: may be null when not applicable.

client.firstName string · nullable · Example: Anna

Nullable: may be null when not applicable.

client.lastName string · nullable · Example: Svensson

Nullable: may be null when not applicable.

client.companyName string · nullable · Example: null

Nullable: may be null when not applicable.

billing object
billing.amount number · nullable required · Example: 199

Recurring fixed-cycle amount in the resource currency. Null when no fixed recurring amount applies, such as PAYG Cloud VPS billing.

billing.currencyCode string required · Example: SEK
billing.billingCycle string · nullable · enum required · Example: annually

Canonical billing cycle. VPS services with isPayg: true still report monthly for summary display; use isPayg to distinguish PAYG Cloud VPS from fixed-cycle VPS.

monthly
quarterly
semiannually
annually
biennially
triennially
free
billing.isPayg boolean required · Example: false

For VPS service/order billing, true means pay-as-you-go Cloud VPS and false means fixed-cycle/prepaid VPS. Non-VPS resources normally return false.

billing.periodYears integer · nullable · Example: 1

Nullable: may be null when not applicable.

invoice object | null
invoice.id string required · Example: inv_01hxa3b4c5d6e7f8g9h0j1k2m3
invoice.number string · nullable required · Example: 202600001

Nullable: may be null when not applicable.

invoice.amount number required · Example: 159
invoice.currencyCode string required · Example: SEK
invoice.dueAt string · nullable required · Example: 2026-05-11T23:59:59.000Z

Nullable: may be null when not applicable.

invoice.status string · enum required · Example: unpaid
paid
unpaid
partially_paid
draft
cancelled
refunded
invoice.paymentUrl string · nullable required · Example: /billing?invoice=202600001

Nullable: may be null when not applicable.

invoice.totals object required
invoice.dates object required
paymentStatus object
paymentStatus.status string · enum · Example: unpaid
paid
unpaid
credit_note
pending
unknown
paymentStatus.reason string · nullable · Example: Invoice is unpaid.

Nullable: may be null when not applicable.

actions object
actions.canRetry object
actions.canRetry.allowed boolean required · Example: true
actions.canRetry.reason string · nullable required · Example: null

Nullable: may be null when not applicable.

actions.canRetry.code string · nullable · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canCancel object
actions.canCancel.allowed boolean required
actions.canCancel.reason string · nullable required

Nullable: may be null when not applicable.

domains array<object>
hosting array<object>
addons array<object>
upgrades array<object>
invoiceLookupPending boolean · Example: false
restoreIntents object

Present when a regular VPS order should restore an existing backup after provisioning. dispatchDeferred: true means the durable restore intent was stored and will be retried from the account-created webhook.

restoreIntents.requested integer · Example: 1
restoreIntents.created integer · Example: 1
restoreIntents.queued integer · Example: 1
restoreIntents.skipped integer · Example: 0
restoreIntents.dispatchDeferred boolean · Example: false
createdAt string · nullable

contractAcceptedAt string · nullable · Example: null

notes string · nullable · Example: null

referenceNumber string · nullable · Example: null

400 Invalid request. The response body is an RFC 7807 Problem Details document.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
401 Unauthorized. Authentication is required.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
403 Forbidden. The caller lacks a required scope or does not own the resource.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
404 Not found. The resource does not exist or is not owned by the caller.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
409 Cart conflict. code is domain_conflict when one or more domains in the cart cannot be ordered (the conflicts array lists each domain with a reasonCode such as duplicate_in_cart, already_ordered, already_in_account_pending, already_in_account, or already_in_system), or promo_rejected when a promotion cannot be applied (priceCorrections lists the corrected regular prices to retry with).
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
429 Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
500 Internal error. Retry later or contact support if the issue persists.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on detail.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when code is invalid_request.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
POST https://cloud.hostup.se/api/v2/orders
For AI assistants
View as Markdown
cURL 
curl -X POST "https://cloud.hostup.se/api/v2/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "bankgiro",
    "items": [
      {
        "type": "domain",
        "action": "register",
        "domainName": "example.se",
        "years": 1,
        "acceptedTerms": [
          "se_registration_terms"
        ]
      }
    ]
  }'
Response 
// Order
{
  "id": "ord_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "number": "O-HXA3B4C5",
  "status": "pending",
  "type": "new",
  "invoiceId": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "checkoutUrl": "https://cloud.hostup.se/billing?invoice=202600001",
  "client": {
    "id": null,
    "email": "user@example.com",
    "firstName": "Anna",
    "lastName": "Svensson",
    "companyName": null
  },
  "billing": {
    "amount": 199,
    "currencyCode": "SEK",
    "billingCycle": "annually",
    "isPayg": false,
    "periodYears": 1
  },
  "invoice": null,
  "paymentStatus": {
    "status": "unpaid",
    "reason": "Invoice is unpaid."
  },
  "actions": {
    "canRetry": {
      "allowed": true,
      "reason": null,
      "code": "pending_order"
    },
    "canCancel": {
      "allowed": true,
      "reason": null
    }
  },
  "domains": [
    {}
  ],
  "hosting": [
    {}
  ],
  "addons": [
    {}
  ],
  "upgrades": [
    {}
  ],
  "invoiceLookupPending": false,
  "restoreIntents": {
    "requested": 1,
    "created": 1,
    "queued": 1,
    "skipped": 0,
    "dispatchDeferred": false
  },
  "createdAt": null,
  "contractAcceptedAt": null,
  "notes": null,
  "referenceNumber": null
}

// Variant 2
{}
Request Body Register .se domain with stored profile 
{
  "paymentMethod": "bankgiro",
  "items": [
    {
      "type": "domain",
      "action": "register",
      "domainName": "example.se",
      "years": 1,
      "acceptedTerms": [
        "se_registration_terms"
      ]
    }
  ]
}