# Domains

> Give a deployment a permanent address: platform subdomains, custom domains and the personal setup instructions that connect them, domain status, and switching deployments for instant rollbacks.

Source: https://docs.shipstatic.com/domains

A domain gives your deployment a permanent, human-readable address. There are two kinds: platform domains like `my-app.shipstatic.com`, ready at once, and custom domains like `www.example.com`, which you connect with a DNS record or two.

Available via [Web](https://docs.shipstatic.com/web), [CLI](https://docs.shipstatic.com/cli), [SDK](https://docs.shipstatic.com/sdk), [MCP](https://docs.shipstatic.com/mcp), and [API](https://docs.shipstatic.com/api).

**Domains need an account.** Publishing does not, but a domain belongs to someone, so it is the first step that does. If you deployed without an account, open the claim link that came back with the deployment. Claiming is free, takes one sign-in, and makes the deployment permanently yours so you can point a domain at it.

## Platform domains

Subdomains of `shipstatic.com`, like `my-app.shipstatic.com`.

- No DNS to set up: verified from the start, and live as soon as a deployment is linked
- One name of 6 to 63 characters: lowercase letters, digits and hyphens
- A name shaped like a deployment address (`happy-cat-abc1234`) is refused
- Available on every plan, up to that plan's cap (see [Plans](https://docs.shipstatic.com/plans))

## Custom domains

Your own domain, like `www.example.com` or `blog.example.com`, on a plan that includes custom domains (see [Plans](https://docs.shipstatic.com/plans)). You need to own the domain already: ShipStatic connects domains but does not sell them. Any domain registrar works, such as [Namecheap](https://www.namecheap.com), [Hover](https://www.hover.com) or [Porkbun](https://porkbun.com). We are not affiliated with them.

A custom domain is always a subdomain. `example.com` on its own is not hosted: add `www.example.com`, and visitors to `example.com` are redirected to it.

### Connecting one

1. **Add the domain.** In the console, or with `set` on any interface.
2. **Follow your setup instructions.** Every custom domain gets its own instructions page, written for the DNS provider that manages it (Cloudflare, GoDaddy, Namecheap and many more). It says which records to add, where to add them, and what to do when something goes wrong. It reaches you three ways:
   - by email, the moment you add the domain ("How to connect www.example.com")
   - in the [Web](https://docs.shipstatic.com/web) console, on the domain's Connect screen, under See Instructions
   - from `share` on the [CLI](https://docs.shipstatic.com/cli), [SDK](https://docs.shipstatic.com/sdk), [MCP](https://docs.shipstatic.com/mcp) and [API](https://docs.shipstatic.com/api)
3. **Link a deployment.** A domain serves nothing until a deployment is linked. You can link one before DNS is ready: the domain goes live the moment both are in place.

The instructions page is the place to work from. The rest of this section explains what happens around it.

### When someone else manages your DNS

The instructions are made to be passed on. Forward the email, or send the link: whoever opens it sees your records and the steps for your provider, and needs no account or credentials. Once the domain is connected, the same link says "All set" instead.

### Verification is automatic

You do not need to tell the platform that the records are in place. It checks when you add the domain, again after 15 and 30 minutes, then every hour for three days, then every day for as long as the domain exists and is not paused. The first check that finds every record verifies the domain, provisions its HTTPS certificate, and emails you that it is live.

Verify (Check now, in the console) checks at once and restarts that schedule. It can run once every 10 minutes per domain.

### The records

Your instructions carry the exact records and values, and `records` answers the same list on every interface. Their shape:

| Domain | Records |
|--------|---------|
| `www.example.com` | CNAME `www`, and A `@`, which redirects `example.com` to `www.example.com` |
| `blog.example.com` | CNAME `blog` |
| `app.team.example.com` | CNAME `app.team` |

The CNAME is where the site is served. The A record exists only for the redirect: no site is ever served on `example.com` itself.

`verification` says how far DNS has got, underneath an `unverified` status:

| Verification | Meaning |
|--------------|---------|
| `pending` | The CNAME is not in place, so the site is not served |
| `partial` | A `www` domain's CNAME is in place and its A record is not, so the site is served and `example.com` does not redirect yet |
| `verified` | Every required record is in place |

### Wildcard CNAME

If you add several subdomains of one domain, one wildcard record can stand in for their CNAMEs: point `*.example.com` at the CNAME target your instructions give. It covers names one level down (`blog.example.com`, not `app.team.example.com`), and a `www` domain still needs its A record.

## Troubleshooting

Your instructions page has a troubleshooting section written for your provider, so start there. Nearly every custom domain that does not connect has one of these causes, and none of them fixes itself with time:

- **An old record for the same name.** A domain that pointed at a previous site or a parking page still has that record. Delete any A, AAAA or CNAME record with the same name as ours, then add ours. Email records (MX, TXT) stay as they are.
- **The domain is not registered.** Buy it from any domain registrar first. DNS cannot be set up for a name nobody owns.
- **Cloudflare's proxy.** On Cloudflare, set the record's Proxy status to DNS only (the grey cloud, not the orange one). Behind the proxy the record cannot be seen, and the domain never connects.
- **DNS managed somewhere else.** The records belong wherever the domain's DNS is managed, which is not always where it was bought. Your instructions name the provider that was detected.

Some changes do take time. Some DNS providers are slow to publish a change, and when a new record replaces an old one for the same name, DNS servers can keep answering with the old one until it expires. Checking sooner, Check now included, cannot shorten that, and there is nothing to redo: the platform keeps checking and emails you when the domain is live.

Still stuck? Write to [hello@shipstatic.com](mailto:hello@shipstatic.com) with a screenshot of your DNS records.

## Status

`status` is the one word to read: what the domain needs from you. Read it rather than working it out from the other fields.

| Status | Meaning | What to do |
|--------|---------|------------|
| `unverified` | The required DNS records are not all in place yet | Follow your setup instructions, and see [Troubleshooting](https://docs.shipstatic.com/domains#troubleshooting) if it stays here |
| `unlinked` | DNS is right and nothing is published there, so visitors see the reserved page | Link a deployment |
| `live` | It serves the linked deployment | Nothing |
| `paused` | The plan no longer includes this domain (e.g. a paid plan downgraded). DNS is kept but the domain stops serving, and visitors see the same page a reserved domain shows. It serves again after an upgrade | Delete another domain, or upgrade |

A platform domain has no records to set up, so it is verified from the start and is never `unverified`.

## Properties

| Property | Description |
|----------|-------------|
| `domain` | Fully qualified domain name |
| `url` | Full URL to the domain |
| `status` | What the domain needs from you: the one word to read (see [Status](https://docs.shipstatic.com/domains#status)) |
| `deployment` | Linked deployment hostname, or `null` if reserved |
| `linked` | When a deployment was last linked, or `null` |
| `links` | How many times a deployment has been linked |
| `verification` | The DNS fact: `pending`, `partial` or `verified` |
| `verified` | When DNS *last* became verified, or `null` if it never has. It is never cleared, so a domain whose records later move away keeps it: read `verification` to know whether DNS is right *now* |
| `verifications` | How many verification attempts |
| `paused` | When plan enforcement paused serving, or `null` |
| `labels` | Mutable tags for organization |
| `created` | Creation timestamp |

## Lifecycle

1. **Reserve.** Create a domain without linking it to a deployment. Visitors see a page saying the domain is set up but nothing is published there yet.
2. **Link.** Point the domain at a deployment.
3. **Switch.** Repoint it to a different deployment, atomically. This is how you roll back.
4. **Delete.** Remove the domain entirely.

**No unlinking.** Once a domain is linked, it cannot be set back to empty. Switch to a different deployment or delete the domain.

## Names

Domain names are case-insensitive: `WWW.Example.COM` is stored as `www.example.com`. They are ASCII, so enter an internationalized name in its `xn--` form.

## Operations

| Operation | Description |
|-----------|-------------|
| Set | Create, link, switch, or label a domain (upsert) |
| List | All domains on your account |
| Get | Details of a specific domain |
| Delete | Delete a domain |
| Validate | Pre-flight check: is the name valid and available? |
| Verify | Check DNS now, and restart the automatic schedule |
| Records | The DNS records the domain needs |
| DNS | Which DNS provider manages the domain (Cloudflare, Namecheap, …) |
| Share | The link to the domain's setup instructions. Anyone can open it, no account needed |