Skip to content

Change the main domain of web hosting

POST /api/v2/shared-hosting/{accountId}/actions/change-main-domain

Change the main domain of a web hosting account. Check the change first with GET /api/v2/shared-hosting/{accountId}/actions/change-main-domain and the new domain. The control panel username, files and databases stay as they are. The website folder is served on the new domain. Mailboxes on the old main domain get addresses on the new one. The old main domain leaves the account unless you send keepPreviousDomain: true while actions.canKeepPreviousDomain on the GET is open. No domain registration is cancelled, renewed or transferred. When the new domain uses Hostup’s nameservers and has no website or e-mail records elsewhere, its DNS is pointed to the account. When it has such records, the call returns 409 dns_setup_choice_required until you send dnsSetupPreference. An addon domain on the account can take over as main domain. Its folder becomes public_html and the old main site is kept in a folder named after its domain. promotion in the response says what was put back. Other domains on the account stay. The request is safe to repeat. A repeat for a domain that is already the main domain finishes what an interrupted request left undone and returns changed: false. A repeat within 15 minutes of a finished change returns that change’s result. The account must be active and on cPanel.

Authentication: An API key with the scopes write:hosting and console:services. About keys and scopes

Request

Path parameters

accountIdstringrequired
The web hosting account ID (acct_…).

Body

domainstringrequired
The new main domain, without www.. The www name is added for you. It must be a registered domain with public nameservers and not on any hosting account. A domain registered with Hostup or with a DNS zone at Hostup must be on your own account.
keepPreviousDomainboolean
Keep the old main domain on the same website folder so it keeps showing the site. It uses one addon domain on the plan. Its DNS is not changed and its old mailbox addresses are not created again. When actions.canKeepPreviousDomain on the GET is closed, the old domain is removed anyway. Default false.
dnsSetupPreferencestring
What to point at the account for the new domain when it already has records elsewhere. full: website and e-mail. website-only: website, existing e-mail records stay. email-only: e-mail, existing website records stay. none: no DNS changes. Needed when the GET shows target.dnsSetup.requiresChoice. One of full, email-only, website-only, none.

Example

POST /api/v2/shared-hosting/{accountId}/actions/change-main-domain
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "shop.example.com"
}'

Responses

200 The requested domain is now the main domain.

Response 200
{
"mainDomain": "shop.example.com",
"previousMainDomain": "example.com",
"changed": true,
"emailAccounts": [
"info@example.se"
],
"previousDomain": {
"domain": "example.com",
"status": "detached",
"reason": null
},
"certificate": {
"status": "requested"
},
"dns": {
"usesHostupNameservers": true,
"appliedPreference": "full"
},
"promotion": null
}
Response fields
mainDomainstring
The account’s main domain after the change.
previousMainDomainstring or null
The main domain before the change. Null when the domain was already the main domain and nothing was left to finish.
changedboolean
True when this request changed the main domain. False when it was already in place and only the remaining steps were done.
emailAccountsarray of any or null
Mailboxes on the new main domain. Null when they could not be read.
previousDomainobject or null
What happened to the old main domain. Null when previousMainDomain is null.
certificateobject
The SSL certificate for the new domain.
statusstring
requested: the certificate is being issued. request_failed: it could not be started now and is issued at the next automatic check. One of requested, request_failed.
dnsobject or null
DNS for the new main domain. Null when the domain was already the main domain or its DNS could not be read.
promotionobject or null
What was put back when an addon domain took over as main domain. Null for any other change and on a repeat for a domain that is already the main domain.

Errors

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

400The request body is not valid.
401Unauthorized. Authentication is required.
403The domain belongs to another customer account or has a DNS zone with Hostup that is not on your account (domain_not_owned).
404Not found. The resource does not exist or is not owned by the caller.
409The main domain cannot be changed now. Nothing was changed. The code says why: main_domain_change_unavailable, domain_conflict, domain_not_ready, domain_not_eligible, dns_setup_choice_required, service_change_in_progress or account_not_eligible_cpanel.
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.
502The change could not be finished or confirmed. Sending the same request again is safe. mainDomainChanged: true means the main domain was changed and only the last step is missing. When an addon domain change stopped part-way and could not be undone, detail asks you to contact support.
503The domain’s ownership could not be checked right now. Try again shortly.