> ## 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, for example
`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 is where most people get stuck.

## What you need

* A domain you own, registered with any registrar: Namecheap, Cloudflare, GoDaddy, or another.
* 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.** This only works if your
  DNS provider supports ALIAS or ANAME records, or if you migrate DNS to Cloudflare.

If you are 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, for example `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, use only the subdomain part as the name, for example `shop`. Most DNS interfaces
append your domain automatically.

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

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

### Step 3: Trigger verification

Back in Shoppex, open **Domains**, click the row for your new domain, then click
**Check Verification**.

This step 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 TXT records in your registrar's DNS dashboard. Click **Check Verification** again in
Shoppex. If DNS has propagated, the status moves to **Verified**.

DNS propagation typically takes a few minutes to a few hours, depending on your registrar. There
is no fixed time. If it is not ready the first time, click **Check Verification** again.

### 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 certificate is live. This typically
takes a few minutes to an hour.

If SSL stays on **Pending** for more than an hour, use **Refresh SSL** in the domain row's menu
to start the certificate process again.

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

## Setup — apex / root domain

Apex domains do not allow CNAME records, by the DNS specification. 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. The free plan works.
2. Update your registrar's nameservers to the two Cloudflare gives you when you add the domain.
3. Once Cloudflare has the domain, follow the subdomain setup steps above. Add a CNAME at `@`
   pointing to `custom.myshoppex.io`.
4. 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, for example DNSimple, NS1, easyDNS, and Hover, support ALIAS or ANAME
records: a CNAME equivalent that is legal at the apex. If your provider supports it, use it the
same way as a CNAME, pointing to `custom.myshoppex.io`.

### Option C: Use a subdomain instead

If you do not want to move DNS, or your provider does not support ALIAS, connect
`www.yourbrand.com`, or another 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 extra domains to a single shop, for example a typo-catching alias or a
regional variant. Add them the same way, under **Store → Domains**, but choose the
**Additional** type instead of Custom.

The Custom domain is your shop's primary URL. Additional domains route to the same content, then
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.
Shoppex keeps the DNS records and the Cloudflare-side configuration, so re-enabling is instant
and does not require re-verifying DNS.

## Common pitfalls

* **"Domain already registered to Paylix."** This is an old internal error message. It means 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)
  until the domain is fully verified and SSL is active. You can turn the proxy on afterward, but
  for storefronts there is rarely a reason to.
* **No automatic retry.** Shoppex does not poll DNS in the background. After you add records,
  click **Check Verification** in the dashboard yourself. If it does not verify, check the
  records again, then try once more. DNS propagation can still be in progress.
* **Subdomain works, apex does not.** If `shop.yourbrand.com` verifies but `yourbrand.com` does
  not, your DNS provider does not support ALIAS at the root. Use Option A or Option C above.
* **Apex with `A` records pointing somewhere else.** An existing A record at `@` that points to
  a different server, for example a website builder or an old host, conflicts with this setup.
  Delete that record before you add the ALIAS record or the CNAME flattening.
* **TLS taking forever.** If SSL stays on `pending_issuance` for more than an hour, click
  **Refresh SSL** in the domain row's dropdown menu. This starts Cloudflare's certificate
  process again.