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

**Change the main domain of web hosting**

Change the main domain of a web hosting account. Check the change first with [`GET /api/v2/shared-hosting/{accountId}/actions/change-main-domain`](/endpoints/webhosting-services/get-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.

### Related Endpoints

- `GET /api/v2/shared-hosting/{accountId}/actions/change-main-domain`: Check a main domain change for web hosting
- `GET /api/v2/shared-hosting/{accountId}/actions/sso`: Check control panel login for web hosting
- `POST /api/v2/shared-hosting/{accountId}/actions/sso`: Create a control panel login link

### Headers

- `Authorization`: Bearer $HOSTUP_API_KEY
- Scopes: `write:hosting`, `console:services`
- `Content-Type`: application/json

### Parameters

- `accountId` (path, string, required): The web hosting account ID (`acct_…`). Example: `acct_01hxa3b4c5d6e7f8g9h0j1k2m3`

### Request Body

- `domain` (string, required): 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. Example: `example.se`
- `keepPreviousDomain` (boolean, optional): 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.
- `dnsSetupPreference` (string, optional): 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`.
  Allowed values: full, email-only, website-only, none

### Request Examples

#### Change the main domain

```bash
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"
  }'
```

```json
{
  "domain": "shop.example.com"
}
```

#### Change the main domain and keep the old one showing the site

```bash
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",
    "keepPreviousDomain": true
  }'
```

```json
{
  "domain": "shop.example.com",
  "keepPreviousDomain": true
}
```

#### Keep the new domain's e-mail where it is

```bash
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",
    "dnsSetupPreference": "website-only"
  }'
```

```json
{
  "domain": "shop.example.com",
  "dnsSetupPreference": "website-only"
}
```

### Response Schema

- `mainDomain` (string, required): The account's main domain after the change. Example: `example.se`
- `previousMainDomain` (string, required, nullable): The main domain before the change. Null when the domain was already the main domain and nothing was left to finish. Example: `example.com`
- `changed` (boolean, required): True when this request changed the main domain. False when it was already in place and only the remaining steps were done.
- `emailAccounts` (array<any>, required, nullable): Mailboxes on the new main domain. Null when they could not be read.
- `previousDomain` (object, required, nullable): What happened to the old main domain. Null when `previousMainDomain` is null.
- `certificate` (object, required): The SSL certificate for the new domain.
- `certificate.status` (string, required): `requested`: the certificate is being issued. `request_failed`: it could not be started now and is issued at the next automatic check.
  Allowed values: requested, request_failed
- `dns` (object, required, nullable): DNS for the new main domain. Null when the domain was already the main domain or its DNS could not be read.
- `promotion` (object, required, nullable): 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.

### Responses

#### 200 - The requested domain is now the main domain.
```json
{
  "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
}
```

#### 400 - The request body is not valid.
```json
{
  "type": "https://developer.hostup.se/errors/invalid_request",
  "title": "Invalid request",
  "status": 400,
  "detail": "`domain` must be a full domain name such as \"example.com\".",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain",
  "code": "invalid_request",
  "errors": [
    {
      "pointer": "/body/domain",
      "detail": "`domain` must be a full domain name such as \"example.com\".",
      "code": "invalid_request"
    }
  ]
}
```

#### 401 - Unauthorized. Authentication is required.
```json
{
  "type": "https://developer.hostup.se/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication is required.",
  "code": "unauthorized",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 403 - The domain belongs to another customer account or has a DNS zone with Hostup that is not on your account (`domain_not_owned`).
```json
{
  "type": "https://developer.hostup.se/errors/domain_not_owned",
  "title": "Domain cannot become the main domain",
  "status": 403,
  "detail": "This domain belongs to another customer account.",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain",
  "code": "domain_not_owned"
}
```

#### 404 - Not found. The resource does not exist or is not owned by the caller.
```json
{
  "type": "https://developer.hostup.se/errors/not_found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource could not be found.",
  "code": "not_found",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 409 - The 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`.
```json
{
  "type": "https://developer.hostup.se/errors/main_domain_change_unavailable",
  "title": "Main domain cannot be changed",
  "status": 409,
  "detail": "The current main domain has subdomains. Contact support and we will change the main domain for you.",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain",
  "code": "main_domain_change_unavailable"
}
```

#### 429 - Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
```json
{
  "type": "https://developer.hostup.se/errors/rate_limit_exceeded",
  "title": "Too many requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later.",
  "code": "rate_limit_exceeded",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 500 - Internal error. Retry later or contact support if the issue persists.
```json
{
  "type": "https://developer.hostup.se/errors/internal_error",
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error occurred. Retry later or contact support if the issue persists.",
  "code": "internal_error",
  "instance": "/api/v2/resource",
  "requestId": "req_01hxa3b4c5d6e7f8g9h0j1k2m3",
  "timestamp": "2026-04-27T12:34:56.000Z"
}
```

#### 502 - The 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.
```json
{
  "type": "https://developer.hostup.se/errors/upstream_failed",
  "title": "Upstream request failed",
  "status": 502,
  "detail": "The main domain could not be changed right now. The account still uses its previous main domain.",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain",
  "code": "upstream_failed"
}
```

#### 503 - The domain's ownership could not be checked right now. Try again shortly.
```json
{
  "type": "https://developer.hostup.se/errors/upstream_unavailable",
  "title": "Domain could not be verified",
  "status": 503,
  "detail": "The domain's ownership could not be verified right now. Try again shortly.",
  "instance": "/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/change-main-domain",
  "code": "upstream_unavailable"
}
```
