Domains and addresses

Take a free short name

Pick a name: lower-case letters, numbers, and dashes.
Connect it.
“Give my shop site the address brand-shop.simple-host.app.”
POST /v1/sites/{site}/domain with {"domain":"brand-shop.simple-host.app"}. The answer has "status":"active".
Your sites page, the site’s Manage menu, Domain. Type the name and press Connect.

Connect it.
“Connect shop.brand.com to my shop site.”
POST /v1/sites/{site}/domain with {"domain":"shop.brand.com"}.
Manage, then Domain. Type the domain and press Connect.

Add these records at your registrar, copied exactly from the answer or the Domain panel:

Type	Name	Value
CNAME (subdomain) or A (bare domain)	`shop`	`cname.simple-host.app`, or the IP shown
TXT	`_simple-host.shop`	`sh-...` (your site’s token)
CNAME for www, or A for the bare domain	`www` or `@`	as shown, only if the answer lists it

Leave every other record alone, MX included. Keep the TXT record in place.

Wait for the check. Checks run about every two minutes.
“Is shop.brand.com live yet?”
GET /v1/sites/{site}/domain until status is active and certificate_status is live. POST .../domain/check checks now; last_error says what is missing.
The badge next to the site’s name. Press Check again.
Open https://shop.brand.com/. A page means it is done.

Add the records the same day: an unproven connection expires after 24 hours.

http:// redirects but https:// fails

If certificate_status is failed, remove any AAAA record pointing elsewhere and any CAA record that does not allow Let’s Encrypt.

Disconnect it.
“Disconnect shop.brand.com.”
DELETE /v1/sites/{site}/domain?domain=shop.brand.com.
Manage, then Domain, then Disconnect.
Remove the records at your registrar.

Connect it.
“Put all my sites under *.clients.brand.com.”
POST /v1/me/address-families with {"suffix":"*.clients.brand.com"}. Add "site_prefix":"client-" to match only sites whose names start with it.
Address families on your sites page, or Manage, Domain, All my sites (*.name). Type the domain and press Connect.
Add a CNAME *.clients to cname.simple-host.app, and a TXT _simple-host.clients with the value shown. Keep the TXT record.
Wait until the certificate status changes from waiting_for_operator to live. Still waiting after a day? Write to support@simple-host.app.
Open https://<site>.clients.brand.com/. A page means it is done.

"canonical": false keeps each site’s own address as the main one.

Code	Means	Do this
`domain_taken` (409)	Name belongs to another site or account	Pick another name
`domain_releasing` (409)	Just disconnected	Try again in 10 minutes
`invalid_domain` (400)	Not a valid domain	Check the spelling
`name_reserved` (400)	Kept for the platform, like `www` or `admin`	Pick another name
`use_address_family` (400)	A wildcard sent to a site’s domain route	Use `/v1/me/address-families`