> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoppex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domain

> Step-by-step DNS walkthrough to run your shop on your own domain.

By default your shop lives at `yourshop.shoppex.io`. To run it on your own domain (e.g.
`shop.yourbrand.com` or `yourbrand.com`), add a custom domain from **Store → Domains**
(`/store/domains`).

This page walks through the DNS setup in detail because it's where most people get stuck.

## What you'll need

* A domain you own (registered with any registrar — Namecheap, Cloudflare, GoDaddy, anywhere).
* Access to that domain's **DNS settings**.
* A few minutes for DNS to propagate.

## Subdomain vs. apex (root domain)

You can connect either:

* **Subdomain** — `shop.yourbrand.com`, `store.yourbrand.com`, `www.yourbrand.com`. **Easier.**
  Works on every DNS provider.
* **Apex / root domain** — `yourbrand.com` with no prefix. **Harder.** Only works if your DNS
  provider supports ALIAS / ANAME records, or if you migrate DNS to Cloudflare.

If you're not sure, start with a subdomain. You can switch to apex later.

## Setup — subdomain

### Step 1: Add the domain in Shoppex

1. Open **Store → Domains** in your Shoppex dashboard.
2. Click **Add Custom Domain**.
3. Type your subdomain (e.g. `shop.yourbrand.com`).
4. Click **Add Domain**.

Shoppex shows a **DNS Configuration** dialog with the initial CNAME:

| Type  | Name                 | Target                |
| ----- | -------------------- | --------------------- |
| CNAME | `shop.yourbrand.com` | `custom.myshoppex.io` |

For the CNAME, **the name should be just the subdomain part** (e.g. `shop`) — most DNS UIs
auto-append your domain.

### Step 2: Add the CNAME to your DNS provider

Open your registrar's DNS dashboard and add the CNAME record exactly as shown. Save.

### Step 3: Trigger verification

Back in Shoppex → **Domains** → click the row for your new domain → **Check Verification**.

This is the step that pulls the **TXT records** from Cloudflare. Shoppex shows you the two
TXT records you now need to add — one for ownership verification, one for SSL/TLS validation.
Both names and values are unique to your domain, copy them exactly.

### Step 4: Add the TXT records and verify again

Add the two TXTs in your registrar's DNS dashboard. Click **Check Verification** again in
Shoppex. If DNS has propagated, status moves to **Verified**.

DNS propagation typically takes a few minutes to a few hours, depending on your registrar —
there's no fixed time. Click **Check Verification** again if it isn't ready the first time.

### Step 5: Wait for SSL

After verification, Cloudflare issues an SSL certificate for the domain. The status in the
dashboard moves from **Pending** to **Active** once the cert is live. This typically takes
a few minutes to an hour.

If SSL is stuck on **Pending** for more than an hour, use the **Refresh SSL** option in the
domain row's menu to retrigger provisioning.

Once active, your shop is live on the custom domain.

## Setup — apex / root domain

Apex domains don't allow CNAME records (per the DNS spec). You need one of these:

### Option A: Migrate DNS to Cloudflare (recommended)

Cloudflare supports **CNAME flattening at the root** — you can put a CNAME at `@` and
Cloudflare resolves it transparently. This is the cleanest solution.

1. Add your domain to Cloudflare ([free plan works](https://www.cloudflare.com/plans/)).
2. Update your registrar's nameservers to Cloudflare's (Cloudflare gives you two when you add
   the domain).
3. Once Cloudflare has the domain, follow the regular DNS setup steps above. Add a CNAME at
   `@` pointing to `custom.myshoppex.io`.
4. **Important:** keep the CNAME on **DNS only** (grey cloud icon, not orange). Cloudflare
   proxying breaks the custom-hostname verification.

### Option B: ALIAS / ANAME record at your existing DNS

Some DNS providers (DNSimple, NS1, easyDNS, Hover) support ALIAS or ANAME records — a
CNAME-equivalent that's legal at the apex. If yours supports it, use it the same way as a
CNAME pointing to `custom.myshoppex.io`.

### Option C: Use a subdomain instead

If you don't want to move DNS or your provider doesn't support ALIAS, the simplest path is to
connect `www.yourbrand.com` (or any other subdomain) instead of the bare root. You can then
configure your DNS to **redirect** `yourbrand.com` to `www.yourbrand.com` — most registrars
offer this as a simple toggle.

## Multiple domains pointing at one shop

You can attach additional domains to a single shop — useful for typo-catching aliases or
regional variants. Add them the same way under **Store → Domains**, choosing the
**Additional** type instead of Custom.

The Custom domain is your shop's primary URL. Additional domains route to the same content but
redirect to the Custom domain for SEO consolidation.

## Removing a custom domain

Disabling a custom domain from the dashboard reverts the shop to its default `*.shoppex.io`
URL. The DNS records and Cloudflare-side configuration are remembered — re-enabling is instant
and doesn't require re-verifying DNS.

## Common pitfalls

* **"Domain already registered to Paylix."** Old internal error message — the domain is
  already in use by another Shoppex shop (Paylix is a legacy name). Open a ticket through
  Discord or Telegram if you believe the domain is yours.
* **Cloudflare proxy turned on during verification.** If the orange-cloud proxy is enabled on
  the CNAME, Cloudflare custom-hostname verification fails silently. Keep it grey-cloud (DNS
  only) at least until the domain is fully verified and SSL is active. You can turn the proxy
  on afterwards — but for storefronts there's rarely a reason to.
* **No automatic retry.** Shoppex doesn't poll DNS in the background. After adding records,
  click **Check Verification** in the dashboard yourself. If it doesn't verify, double-check
  the records and try again — DNS may still be propagating.
* **Subdomain works, apex doesn't.** If `shop.yourbrand.com` verifies but `yourbrand.com`
  doesn't, your DNS provider doesn't support ALIAS at root. Use Option A or C above.
* **Apex with `A` records pointing somewhere else.** If you already had an A record at `@`
  pointing to a different server (a website builder, old host), that conflicts. Delete those
  A records before adding the ALIAS/CNAME flattening.
* **TLS taking forever.** If SSL stays `pending_issuance` for more than an hour, click
  **Refresh SSL** in the domain row's dropdown menu. That re-triggers Cloudflare's
  certificate provisioning.