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 objecttype. Send at least one. An empty list creates no order and answers 200 with accountCreated: false.type is domaintypestringrequireddomain.actionstringrequiredregister for a new registration. transfer for an inbound transfer order. One of register, transfer.domainNamestringrequiredyearsintegeryears says. 1 to 10.eppCodestringaction: 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 stringse_registration_terms. The availability check names the key an extension needs in registryRequirements.registration[].acceptedTermsKey. A missing key answers 400 with domainRequirements.missingAcceptedTerms.registrantContactobjectclientData on the order.typestringprivate for a person, organisation for a company. When you leave it out, a companyName makes it organisation. One of private, organisation.firstNamestringlastNamestringcompanyNamestringtype: organisation.emailstringphoneNumberstringstreetstringcitystringstatestringpostalCodestringcountryCodestringregistrationIdentifierobject | stringbirthDate.valuestringrequiredcountryCodestring or nullnameserverModestringhostup: 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 stringcopyExistingDnsbooleancopyExistingDnsScopestringall: 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.premiumbooleantrue when the availability check returned premium: true for this domain. Premium registrations need it. So do transfers that need a fee confirmation.requiresRegistrarFeeAcceptancebooleantrue to accept the extra registrar fee when the availability check returned requiresRegistrarFeeAcceptance: true for this domain.voucherCodestringprovisional.type is vpstypestringrequiredvps.productSlugstringrequireddata[].slug from GET /api/v2/products/vps. A Cloud VPS is not ordered with this item.billingCyclestringbillingCycles[].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.osstringoperatingSystem option in configurableOptions[] of GET /api/v2/products/vps. A shortcut for configurableOptions.operatingSystem.quantityintegercustomHostnamestringcustomHostnamesarray of stringquantity, 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.configurableOptionsobjectconfigurableOptions[] 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.restoreFromBackupobjectvps_…) 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.sourceVpsIdstringrequiredbackupIdstringrequiredrequiredStorageGbintegerbackupLabelstringvoucherCodestringprovisional.type is shared_hostingtypestringrequiredshared_hosting.productSlugstringrequiredGET /api/v2/products/shared-hosting. One of webbhotell-start, webbhotell-business, webbhotell-unlimited, webbhotell-reseller-unlimited.primaryDomainstringbillingCyclestringbillingCycles[].billingCycle. When you leave it out, the item is ordered and invoiced annually. One of annually, biennially, triennially.migrationobjecttype: "none" when nothing should be moved.typestringrequirednone, wordpress, cpanel, email-only.wpUserstringwordpress migration.wpPassstringwordpress migration.wpAdminUrlstringwordpress migration.cpUrlstringcpanel migration.cpUserstringcpanel migration.cpPassstringcpanel migration.emailPasswordsstringemail-only migration.notesstringmxPreferencesobjectdnsSetupPreference 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.dnsSetupPreferencestringfull: 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 objectdnsSetupPreference website-only or none, or keepExisting without a preference.typestringrequiredA, AAAA, CNAME, MX, TXT, CAA, SRV.namestringrequired@ for the domain itself.valuestringrequiredttlnumberprioritynumberkeepExistingbooleanexistingMx to the new DNS zone. Read only when dnsSetupPreference is left out.existingAarray of objectdnsSetupPreference email-only or none, or keepExistingA without a preference.typestringrequiredA, AAAA, CNAME, MX, TXT, CAA, SRV.namestringrequired@ for the domain itself.valuestringrequiredttlnumberprioritynumberkeepExistingAbooleanexistingA to the new DNS zone. Read only when dnsSetupPreference is left out.existingSpfarray of objectkeepExisting keeps the MX records, Hostup adds include:spf.hostup.se to it.typestringrequiredA, AAAA, CNAME, MX, TXT, CAA, SRV.namestringrequired@ for the domain itself.valuestringrequiredttlnumberprioritynumbervoucherCodestringprovisional.clientDataobjectfirstNamestringlastNamestringcompanyNamestringemailstringaddressobjectstreetstringaddress2string or nullcitystringstatestringpostalCodestringcountryCodestringphoneNumberstringregistrationIdentifierobjectvaluestringcountryCodestring or nullvatNumberstringaccountTypestringprivate, organisation.paymentMethodstringcard: 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.attemptKeystring504 with code TIMEOUT. Send it again later with the same key.asyncbooleantrue 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
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" } ] }'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": "shared_hosting", "productSlug": "webbhotell-start", "billingCycle": "annually", "primaryDomain": "example.com", "migration": { "type": "none" } } ] }'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": "domain", "action": "register", "domainName": "example.se", "years": 1, "acceptedTerms": [ "se_registration_terms" ] } ] }'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": "domain", "action": "transfer", "domainName": "example.com", "years": 1, "eppCode": "YOUR_EPP_CODE", "nameserverMode": "preserve_current" } ] }'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": "domain", "action": "register", "domainName": "example.se", "years": 1, "acceptedTerms": [ "se_registration_terms" ] } ], "clientData": { "countryCode": "SE", "phoneNumber": "+46700000000", "accountType": "private", "registrationIdentifier": { "value": "850507-3412", "countryCode": "SE" } } }'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": "domain", "action": "register", "domainName": "example.se", "years": 1, "acceptedTerms": [ "se_registration_terms" ], "registrantContact": { "type": "private", "firstName": "Anna", "lastName": "Svensson", "email": "user@example.com", "phoneNumber": "+46700000000", "street": "Examplegatan 1", "city": "Stockholm", "state": "Stockholm", "postalCode": "123 45", "countryCode": "SE", "registrationIdentifier": { "value": "850507-3412", "countryCode": "SE" } } } ] }'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}{ "accountCreated": false, "clientId": "client_01hxa3b4c5d6e7f8g9h0j1k2m3", "redirectUrl": null, "reason": "No order was created."}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.
{ "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
idstringnumberstringstatusstringpending, active, completed, cancelled, failed.typestringnew, renew, upgrade, transfer.invoiceIdstring or nullcheckoutUrlstring or nullinvoice.paymentUrl when invoice is present.clientobjectidstring or nullemailstring or nullfirstNamestring or nulllastNamestring or nullcompanyNamestring or nullbillingobjectamountnumber or nullcurrencyCodestringbillingCyclestring or nullmonthly. Use isPayg to tell it apart from a fixed-cycle VPS. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.isPaygbooleanperiodYearsinteger or nullinvoiceobject | nullidstringnumberstring or nullamountnumbercurrencyCodestringdueAtstring or nullstatusstringpaid, unpaid, partially_paid, draft, cancelled, refunded.paymentUrlstring or nulltotalsobjectdatesobjectpaymentStatusobjectstatusstringpaid, unpaid, credit_note, pending, unknown.reasonstring or nullactionsobjectcanRetryobjectallowedbooleanreasonstring or nullcodestring or nullcanCancelobjectallowedbooleanreasonstring or nullallowed is true.domainsarray of objecthostingarray of objectaddonsarray of objectupgradesarray of objectinvoiceLookupPendingbooleanrestoreIntentsobjectdispatchDeferred: true means the restore is saved. It is tried again once the VPS has been created.requestedintegercreatedintegerqueuedintegerskippedintegerdispatchDeferredbooleancreatedAtstring or nullcontractAcceptedAtstring or nullnotesstring or nullreferenceNumberstring or null202 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.
{ "operation": { "status": "pending", "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3" }}Response fields
operationobjectstatusstring202 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.jobIdstringpollUrlstring or nullnull when status is already completed or failed.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden: 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. |
| 404 | With restoreFromBackup: source_vps_not_found (no such VPS in your account) or backup_not_found (no such backup of that VPS). |
| 409 | domain_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). |
| 422 | product_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. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | upstream_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. |
| 503 | domain_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. |