Skip to content

Preview an order

POST /api/v2/orders/preview

Calculates the price of an order without placing it. Nothing is ordered and no invoice is created. Send the same body as POST /api/v2/orders. The response has the price per item, the tax and the total. While the customer is still filling in the form, clientData can be partial. Its countryCode, accountType and vatNumber decide the tax. A call with an API key is priced in the account’s currency. Without those fields it uses the account’s country and VAT number, as the order will. Without a key, tax follows the country of the calling IP address, else Sweden. The key is optional. Send it to get the price your order will have. A key that is not accepted gets no error. The preview is then priced as for a call without a key. A preview with a voucher code is provisional. The voucher is checked again when the order is placed. attemptKey and paymentMethod are accepted and do not change the preview. For a domain item, items[].nameserverMode shows which nameservers the order will use. A premium domain name is priced for one year, whatever years says. For a domain item with registrantContact, the domain_not_eligible check uses that holder’s country and type. Without it, the check uses clientData and then the account. The preview does not check accepted terms, the phone number, the identity number or the EPP code. The order does.

Authentication: None. Anyone can call it.

Request

Query parameters

partialstring
1: an item that fails a registry rule is listed in problems and its items[N] is null. The other items keep their prices. Without it, such an item makes the whole preview answer 422. One of 1.

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/preview
curl -X POST "https://cloud.hostup.se/api/v2/orders/preview" \
-H "Content-Type: application/json" \
-d '{
"paymentMethod": "bankgiro",
"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",
"countryCode": "SE",
"registrationIdentifier": {
"value": "850507-3412",
"countryCode": "SE"
}
}
}
],
"clientData": {
"countryCode": "SE",
"accountType": "private",
"registrationIdentifier": {
"value": "850507-3412",
"countryCode": "SE"
}
}
}'

Responses

200 The price of the order.

Response 200
{
"items": [
{
"productSlug": "domain-se",
"domainName": "example.se",
"type": "domain",
"billingCycle": "annually",
"periodYears": 1,
"nameserverMode": "hostup",
"quantity": 1,
"unitAmount": 79,
"renewalAnnualAmount": 129,
"setupAmount": 0,
"configurableOptionAmounts": [],
"subtotal": 79,
"currencyCode": "SEK"
}
],
"subtotal": 79,
"taxRateDecimal": 0.25,
"taxAmount": 19.75,
"total": 98.75,
"currencyCode": "SEK",
"reverseCharge": false,
"priceAssurance": {
"level": "authoritative",
"reason": null,
"revalidatedAtSubmit": false
},
"problems": []
}
Response fields
itemsarray of object
The priced items, in the order you sent them. With ?partial=1, an item that failed a registry rule is null here and is described in problems.
problemsarray of object
Items that failed a registry rule. Empty unless you send ?partial=1.
pointerstring
The failed item in the request.
itemIndexinteger
Position of the failed item in items, from 0. At least 0.
domainNamestring or null
codestring
reasonCodestring
One of eu_registrant_country, registrant_country, registrant_type.
detailstring
Why the item failed, ready to show.
fieldPointerstring
The request field the registry rule reads.
subtotalnumber
Sum of the item subtotals, before cart-level discounts.
taxRateDecimalnumber
taxAmountnumber
Tax on the amount to pay after cart-level discounts.
totalnumber
The amount to pay, with tax, after discounts.
currencyCodestring
reverseChargeboolean
priceAssuranceobject
levelstring
authoritative when every price was verified. provisional when an item has a voucher code. The voucher is checked again when the order is placed. One of authoritative, provisional.
reasonstring or null
Why the price is provisional. Null for an authoritative preview.
revalidatedAtSubmitboolean
true when a voucher discount is checked again when the order is placed.

Errors

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

400Invalid request. The response body is an RFC 7807 Problem Details document.
422domain_not_eligible: a domain cannot be registered or transferred for this registrant, for example because of the registrant’s country or account type. errors points at the field the rule reads. product_not_orderable: a product in the body cannot be 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 failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.