Skip to content

Create an order

POST /api/v2/orders

Places an order for domains, web hosting or a VPS and creates its invoice. Without an API key it also creates the customer account, from the full clientData.

Look up the values first: VPS plans, web hosting plans, domain rules and availability. POST /api/v2/orders/preview returns the exact price without ordering. The examples show one request for each kind of order.

Always send billingCycle for a VPS. An item without one is ordered and invoiced annually, whatever the plan’s main cycle. A VPS customHostname must be DNS-safe.

Send an attemptKey to make retries safe. A repeat inside the duplicate-prevention window (currently one hour) returns the order the first request created (200) instead of a new one.

Returns 201 with the order and its unpaid invoice. The response has no ID for the new VPS, web hosting account or domain. GET /api/v2/me/open-orders has it in lines[].resource.id once the service exists. Pay the invoice with the saved card, account credit or a payment link. Those calls need write:billing. write:orders alone cannot pay. The guides Order a VPS and Pay an invoice go through it step by step.

For a pay-as-you-go Cloud VPS, use POST /api/v2/vps/payg/deployments instead.

Authentication: An API key with the scope write:orders. Also backup:vm: only when an item has restoreFromBackup. About keys and scopes

Request

Body

itemsarray of object
The items to order, 1 to 50. Each item is a domain, a VPS or web hosting, chosen by type. Send at least one. An empty list creates no order and answers 200 with accountCreated: false.
When type is domain
typestringrequired
One of domain.
actionstringrequired
register for a new registration. transfer for an inbound transfer order. One of register, transfer.
domainNamestringrequired
yearsinteger
Years to register or transfer for. A premium domain name is registered for one year, whatever years says. 1 to 10.
eppCodestring
The transfer code from the current registrar, for action: transfer. Leave it out when the extension uses no code. A transfer that needs one and lacks it answers 400 with the pointer /items/0/eppCode.
acceptedTermsarray of string
Registry terms the holder accepts, by key, such as se_registration_terms. The availability check names the key an extension needs in registryRequirements.registration[].acceptedTermsKey. A missing key answers 400 with domainRequirements.missingAcceptedTerms.
registrantContactobject
A different registrant for this domain, when the account holder is not the registrant. Leave it out to use the account profile and any clientData on the order.
typestring
private for a person, organisation for a company. When you leave it out, a companyName makes it organisation. One of private, organisation.
firstNamestring
lastNamestring
companyNamestring
Organisation name, for type: organisation.
emailstring
phoneNumberstring
streetstring
Street address.
citystring
statestring
State, region or county. Some registries require it. For a Swedish registrant use the county if you know it. Otherwise repeat the city.
postalCodestring
Postal code.
countryCodestring
registrationIdentifierobject | string
The registrant’s identity number, required by some registries. For .se and .nu, the personal identity number or organisation number. For a private .fi registrant, the birth date when the registry asks for birthDate.
valuestringrequired
countryCodestring or null
nameserverModestring
Which nameservers the domain gets. hostup: Hostup’s nameservers. custom: the new set in nameservers, at least two. preserve_current: a transfer keeps the nameservers it has at the registry today, even a single one, with no nameserver change. A transfer item may send none of nameserverMode, nameservers and copyExistingDns. If the order also has no web hosting for the same domain, the account’s transfer nameserver setting decides (Account > Domain settings in the client area). An account set to keep current nameservers gets preserve_current. Every other account gets hostup. Registrations and orders without an account get hostup. POST /api/v2/orders/preview returns the mode the order will use as items[].nameserverMode. One of hostup, custom, preserve_current.
nameserversarray of string
copyExistingDnsboolean
copyExistingDnsScopestring
Which current DNS records a transfer copies. all: the whole DNS setup. website: the website records only. email: the e-mail records only. When the same order has web hosting for this domain, that item’s mxPreferences.dnsSetupPreference decides instead. One of all, website, email.
premiumboolean
Set to true when the availability check returned premium: true for this domain. Premium registrations need it. So do transfers that need a fee confirmation.
requiresRegistrarFeeAcceptanceboolean
Set to true to accept the extra registrar fee when the availability check returned requiresRegistrarFeeAcceptance: true for this domain.
voucherCodestring
Voucher code for this item. A preview with one is provisional.
When type is vps
typestringrequired
One of vps.
productSlugstringrequired
The fixed-cycle VPS plan, as data[].slug from GET /api/v2/products/vps. A Cloud VPS is not ordered with this item.
billingCyclestring
Billing cycle, one of the plan’s billingCycles[].billingCycle. Always send it. When you leave it out, the item is ordered and invoiced annually, whatever the plan’s main cycle. One of monthly, quarterly, semiannually, annually, biennially, triennially.
osstring
The operating system slug, from the operatingSystem option in configurableOptions[] of GET /api/v2/products/vps. A shortcut for configurableOptions.operatingSystem.
quantityinteger
1 to 10.
customHostnamestring
The hostname for the VPS. Use only letters, digits, hyphens and dots. Each label starts and ends with a letter or digit. Underscores are not allowed.
customHostnamesarray of string
One hostname per VPS. The entries must be unique. With quantity, the list must have that many entries. Without it, the length of the list is the quantity. Cannot be combined with customHostname. Each entry follows the customHostname rules.
configurableOptionsobject
Plan options for a fixed-cycle VPS, from configurableOptions[] of GET /api/v2/products/vps. Use the key values listed there. A key the plan does not have gets no error. Send SSH keys here as sshKeyIds, not at the top level of the item.
restoreFromBackupobject
Restore a backup of another VPS onto the new one. Send the source VPS ID (vps_…) and the backup ID (bkp_…). Give one hostname, in customHostname or a one-entry customHostnames. The order creates a fixed-cycle VPS and starts the restore once the VPS is ready.
sourceVpsIdstringrequired
backupIdstringrequired
requiredStorageGbinteger
Disk size the backup needs, in GB, as shown in the backup list. The server checks the backup size and the source VPS again. At least 1.
backupLabelstring
voucherCodestring
Voucher code for this item. A preview with one is provisional.
When type is shared_hosting
typestringrequired
One of shared_hosting.
productSlugstringrequired
The web hosting plan slug, from GET /api/v2/products/shared-hosting. One of webbhotell-start, webbhotell-business, webbhotell-unlimited, webbhotell-reseller-unlimited.
primaryDomainstring
The main domain of the hosting account. Use a domain you already have or a domain item in the same order.
billingCyclestring
Billing cycle, one of the plan’s billingCycles[].billingCycle. When you leave it out, the item is ordered and invoiced annually. One of annually, biennially, triennially.
migrationobject
Ask Hostup to move an existing website or mailboxes into the new hosting account. Use type: "none" when nothing should be moved.
typestringrequired
One of none, wordpress, cpanel, email-only.
wpUserstring
WordPress admin username, for a wordpress migration.
wpPassstring
WordPress admin password, for a wordpress migration.
wpAdminUrlstring
WordPress admin URL, for a wordpress migration.
cpUrlstring
URL of the cPanel at your current host, for a cpanel migration.
cpUserstring
cPanel username at your current host, for a cpanel migration.
cpPassstring
cPanel password at your current host, for a cpanel migration.
emailPasswordsstring
Passwords of the mailboxes to move, for an email-only migration.
notesstring
Anything else the migration team should know.
mxPreferencesobject
What happens to the domain’s current DNS records. dnsSetupPreference decides which records the new hosting account sets up. To keep the current mail or website working, also send the records to keep in existingMx or existingA.
dnsSetupPreferencestring
Which DNS records the new hosting account sets up. full: website and e-mail. email-only: e-mail only, the current website stays. website-only: website only, the current e-mail stays. none: DNS stays as it is. One of full, email-only, website-only, none.
existingMxarray of object
The domain’s current MX records. They are copied to the new DNS zone when the current mail stays: dnsSetupPreference website-only or none, or keepExisting without a preference.
typestringrequired
One of A, AAAA, CNAME, MX, TXT, CAA, SRV.
namestringrequired
The record name. @ for the domain itself.
valuestringrequired
ttlnumber
Time to live in seconds. Default 3600.
prioritynumber
Priority, for MX records.
keepExistingboolean
Keep the current mail: copy the records in existingMx to the new DNS zone. Read only when dnsSetupPreference is left out.
existingAarray of object
The website’s current A, AAAA and CNAME records. They are copied to the new DNS zone when the current website stays: dnsSetupPreference email-only or none, or keepExistingA without a preference.
typestringrequired
One of A, AAAA, CNAME, MX, TXT, CAA, SRV.
namestringrequired
The record name. @ for the domain itself.
valuestringrequired
ttlnumber
Time to live in seconds. Default 3600.
prioritynumber
Priority, for MX records.
keepExistingAboolean
Keep the current website: copy the records in existingA to the new DNS zone. Read only when dnsSetupPreference is left out.
existingSpfarray of object
The domain’s current SPF record. When keepExisting keeps the MX records, Hostup adds include:spf.hostup.se to it.
typestringrequired
One of A, AAAA, CNAME, MX, TXT, CAA, SRV.
namestringrequired
The record name. @ for the domain itself.
valuestringrequired
ttlnumber
Time to live in seconds. Default 3600.
prioritynumber
Priority, for MX records.
voucherCodestring
Voucher code for this item. A preview with one is provisional.
clientDataobject
Optional for a signed-in caller. Use it only to add or override the profile fields that the availability or validation response asks for. Required for an order that creates an account.
firstNamestring
lastNamestring
companyNamestring
emailstring
addressobject
streetstring
address2string or null
citystring
statestring
postalCodestring
countryCodestring
phoneNumberstring
registrationIdentifierobject
valuestring
countryCodestring or null
vatNumberstring
accountTypestring
One of private, organisation.
paymentMethodstring
How the order’s invoice will be paid. card: card checkout. swish: Swish. bankgiro: bankgiro payment in SEK. sepa: SEPA bank transfer in EUR. invoice: create the invoice without starting a payment. Send invoice when you pay the invoice through the API afterwards. Account credit is not a payment method here: apply it to the invoice after the order with POST /api/v2/billing/invoices/{id}/actions/apply-credit. One of card, swish, bankgiro, sepa, invoice.
attemptKeystring
Optional caller-generated idempotency key for retry-safe order creation. Use a new value for each order. Send the same value again only to retry the same request after a timeout or lost response. Within the duplicate-prevention window (currently one hour), that retry returns the order and invoice already created instead of a new order. Do not reuse a key for a different cart. The key is matched across all accounts, not only yours. Use a random value such as a UUID for each new order, never a counter. A repeat sent while the first request is still running waits for it. When that wait passes the 30-second request limit, the repeat ends in 504 with code TIMEOUT. Send it again later with the same key.
asyncboolean
true returns 202 with a job at once instead of the order. A completed job holds the order in result. A refused order also ends as completed: its result.status is then 400 or higher and result.code says why. Ignored for an order without an API key, for an item with restoreFromBackup and by POST /api/v2/orders/preview.

Example

POST /api/v2/orders
curl -X POST "https://cloud.hostup.se/api/v2/orders" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"paymentMethod": "invoice",
"items": [
{
"type": "vps",
"productSlug": "vps-xs",
"billingCycle": "monthly",
"os": "ubuntu-24-04",
"customHostname": "app-01.example.com"
}
]
}'

Responses

200 A repeat with the same attemptKey returned the order the first request created. An empty items list also returns 200, as the second shape: no order, only accountCreated, clientId, redirectUrl and reason. Without an API key it still creates a customer account from clientData.

{
"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
}

201 The order was created. invoice holds the invoice to pay. invoice.paymentUrl is a path on https://cloud.hostup.se, not a full URL. A VPS ordered with an API key is set up only after the invoice is paid. It is in GET /api/v2/vps from the moment you order, with serviceStatus pending until it is ready.

Response 201
{
"id": "ord_01hxa3b4c5d6e7f8g9h0j1k2m3",
"number": "2096179503",
"status": "pending",
"type": "new",
"invoiceId": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"checkoutUrl": "/billing?invoice=202600001",
"client": {
"id": "client_01hxa3b4c5d6e7f8g9h0j1k2m3",
"email": null,
"firstName": "Alex",
"lastName": "Example",
"companyName": null
},
"billing": {
"amount": 990,
"currencyCode": "SEK",
"billingCycle": null,
"isPayg": false
},
"invoice": {
"id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3",
"number": "202600001",
"amount": 990,
"currencyCode": "SEK",
"dueAt": "2026-05-11T23:59:59.000Z",
"status": "unpaid",
"paymentUrl": "/billing?invoice=202600001",
"totals": {
"currencyCode": "SEK",
"total": 990,
"amountPaid": 0,
"outstanding": 990
},
"dates": {
"dueAt": "2026-05-11T23:59:59.000Z"
}
},
"paymentStatus": {
"status": "unpaid",
"reason": "Invoice has not been paid yet."
},
"actions": {
"canRetry": {
"allowed": false,
"reason": "The order invoice must be paid before retrying."
},
"canCancel": {
"allowed": true,
"reason": null
}
},
"domains": [],
"hosting": [
{
"name": "Webbhotell Start",
"amount": 990,
"currencyCode": "SEK"
}
],
"addons": [],
"upgrades": [],
"invoiceLookupPending": false,
"createdAt": "2026-04-27T12:00:00.000Z",
"contractAcceptedAt": null,
"notes": null,
"referenceNumber": null,
"pendingManualProcessing": false,
"enableAffiliateTracking": true
}
Response fields
idstring
numberstring
statusstring
One of pending, active, completed, cancelled, failed.
typestring
One of new, renew, upgrade, transfer.
invoiceIdstring or null
checkoutUrlstring or null
Older name for the payment link. Read invoice.paymentUrl when invoice is present.
clientobject
idstring or null
emailstring or null
firstNamestring or null
lastNamestring or null
companyNamestring or null
billingobject
amountnumber or null
The price per billing cycle, in the currency of the resource. Null when there is no fixed price, as for a Cloud VPS.
currencyCodestring
billingCyclestring or null
The billing cycle. A Cloud VPS also shows monthly. Use isPayg to tell it apart from a fixed-cycle VPS. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
isPaygboolean
True for a Cloud VPS, which is billed for what it uses. False for a fixed-cycle VPS. Other services normally return false.
periodYearsinteger or null
invoiceobject | null
idstring
numberstring or null
amountnumber
currencyCodestring
dueAtstring or null
statusstring
One of paid, unpaid, partially_paid, draft, cancelled, refunded.
paymentUrlstring or null
totalsobject
datesobject
paymentStatusobject
statusstring
One of paid, unpaid, credit_note, pending, unknown.
reasonstring or null
actionsobject
canRetryobject
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canCancelobject
allowedboolean
True when the action can be called now.
reasonstring or null
Why the action is blocked, ready to show. Null when allowed is true.
domainsarray of object
hostingarray of object
addonsarray of object
upgradesarray of object
invoiceLookupPendingboolean
restoreIntentsobject
Present when the order restores a backup onto the new VPS. dispatchDeferred: true means the restore is saved. It is tried again once the VPS has been created.
requestedinteger
createdinteger
queuedinteger
skippedinteger
dispatchDeferredboolean
createdAtstring or null
contractAcceptedAtstring or null
notesstring or null
referenceNumberstring or null

202 Sent with "async": true: the order is queued. Poll operation.pollUrl until the job is completed or failed. A completed job holds the order in result. A refused order also completes, with the problem in result: result.status is 400 or higher and result.code says why.

Response 202
{
"operation": {
"status": "pending",
"jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
statusstring
Where the job is. A 202 Accepted response only has pending, queued or in_progress. completed and failed appear when you poll pollUrl. They also appear in a 200 OK response when the action finished during the request. One of pending, queued, in_progress, completed, failed.
jobIdstring
pollUrlstring or null
Where to poll the job while it runs. null when status is already completed or failed.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400invalid_request: the body is wrong, or a domain item lacks details its registry needs. Each entry in errors has a pointer to the field to fix. An unknown field has errors[].code unknown_field. For missing registry details, domainRequirements lists what to add: missingAcceptedTerms, missingProfileFields, missingRegistrantContactFields and missingConfigurableOptions. Nothing was ordered.
401Unauthorized. Authentication is required.
403forbidden: the key lacks the scope the order needs. account_inactive: the account is not active and cannot order. forbidden also when an item has restoreFromBackup and the key lacks backup:vm.
404With restoreFromBackup: source_vps_not_found (no such VPS in your account) or backup_not_found (no such backup of that VPS).
409domain_conflict: one or more domains cannot be ordered. conflicts lists each domain with a reasonCode, for example duplicate_in_cart, already_ordered or already_in_account. domain_not_available: a domain cannot be ordered as sent, for example because it was registered after you checked it. domains names it. domain_order_in_progress: another order for the same domain is being created right now. No new order was made. Check your invoices before you send it again. promo_rejected: the promotion does not apply. priceCorrections lists the regular prices to retry with. With restoreFromBackup, code can also be source_vps_not_ready (the source VPS cannot be read yet), target_storage_too_small (the plan disk, or configurableOptions.storageGb, must be at least requiredStorageGb; extra storage does not count) or target_storage_unconfirmed (the plan’s disk size could not be confirmed).
422product_not_orderable: productSlug, or the domain ending, is not a plan that can be ordered. domain_not_eligible: the holder may not hold this domain ending, for example because of their country or account type. errors points at the field the rule reads. Missing registry details are 400, not 422. invalid_request: without an API key, clientData lacks fields a new customer profile needs. The same code comes back when nameserverMode: preserve_current finds no current nameservers, or more than ten. Nothing was ordered.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502upstream_failed: with nameserverMode: preserve_current, the current nameservers could not be read. The same code comes back when the registry rules for a domain ending could not be loaded. Nothing was ordered. Try again later.
503domain_verification_unavailable: the registry did not answer the availability check, or the price of a premium name could not be confirmed. Nothing was ordered. Send the same body with the same attemptKey again later. upstream_failed: the account status could not be checked right now. Try again later. restore_intent_failed: the order was created but the backup restore could not be scheduled. orderId and invoiceId name the order. Send the same request with the same attemptKey again before you pay. backup_listing_unavailable: the backups of the source VPS could not be listed. Try again later.