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

# Custom Domain

> Point your own domain at a Join Markt storefront.

Connect a branded hostname (for example `shop.yourbrand.com` or `yourbrand.com`) so buyers never see the default `{subdomain}.joinmarkt.com` URL.

<Info>
  Custom domains require a **Premium** or **Business** SaaS plan. Free stores stay on the Join Markt subdomain. See [Plans & billing](/guides/plans-billing).
</Info>

## Statuses

| Status    | Meaning                                                |
| --------- | ------------------------------------------------------ |
| `pending` | Domain saved; DNS not verified yet                     |
| `active`  | TXT + CNAME checks passed                              |
| `failed`  | Verification did not pass (re-check after DNS updates) |

## What you need

* An active Premium or Business subscription
* A domain at any registrar (Cloudflare, Namecheap, Porkbun, …)
* Access to DNS for that domain
* Dashboard → **Domains** for your store

## How Join Markt routes custom domains

Buyer traffic for custom hostnames is pointed at Join Markt’s store edge:

| Record                  | Typical value                          | Proxy                                   |
| ----------------------- | -------------------------------------- | --------------------------------------- |
| Traffic `CNAME`         | `stores.joinmarkt.com`                 | **DNS only** (grey cloud on Cloudflare) |
| Ownership `TXT`         | `_markt-verify` (value from dashboard) | n/a                                     |
| Temporary SSL / CF rows | Shown while hostname is pending        | Follow dashboard labels                 |

Join Markt uses **Cloudflare for SaaS** so HTTPS certificates can be issued for arbitrary customer hostnames.

## Step-by-step

### 1. Open Domains in the dashboard

1. Sign in at [dash.joinmarkt.com](https://dash.joinmarkt.com)
2. Select the store
3. Go to **Domains**
4. Click **Connect** / **Add domain**
5. Enter the hostname (apex or subdomain)

The UI lists the exact DNS rows for your case (CNAME, ownership TXT, and any short-lived SSL verification records).

### 2. Add DNS at your provider

In Cloudflare (recommended) or your registrar DNS panel:

1. Add the **CNAME** from the dashboard → Content `stores.joinmarkt.com`
2. Set Proxy status to **DNS only** (grey cloud)
3. Add the **`_markt-verify` TXT** exactly as shown
4. Add any temporary Cloudflare ownership / ACME rows while status is pending

<Warning>
  Conflicting apex `A` / `CNAME` records for the same host will block verification. Remove or rename conflicts first.
</Warning>

### 3. Optional: redirect `www` to apex

If you sell on `yourbrand.com` and want `www.yourbrand.com` to redirect:

1. Create a proxied `www` record (Cloudflare Redirect Rule)
2. Forward `www.yourbrand.com/*` → `https://yourbrand.com/$1` with **301**

Keep the **store** hostname’s traffic CNAME on `stores.joinmarkt.com` as **DNS only**.

### 4. Verify in Join Markt

1. Return to **Domains**
2. Click **Verify**
3. Wait until status is **active** (DNS + Cloudflare hostname + SSL)

Propagation is usually minutes; worst case up to 24 hours.

### 5. Keep the subdomain as fallback

Leave `{store}.joinmarkt.com` active. It remains a reliable fallback while DNS or certificates catch up.

## Vendor APIs (session required)

Requires seller session + `manageSettings` on the store.

| Method   | Path                                  |
| -------- | ------------------------------------- |
| `GET`    | `/api/stores/{storeId}/domain`        |
| `PUT`    | `/api/stores/{storeId}/domain`        |
| `DELETE` | `/api/stores/{storeId}/domain`        |
| `POST`   | `/api/stores/{storeId}/domain/verify` |

## Troubleshooting

| Symptom             | Check                                                                      |
| ------------------- | -------------------------------------------------------------------------- |
| Verify fails        | Exact CNAME target `stores.joinmarkt.com`, grey cloud, `_markt-verify` TXT |
| SSL pending forever | Temporary ACME / `_cf-custom-hostname` rows still present and correct      |
| Wrong store content | Host matches the store you assigned in Domains                             |
| Plan error          | Store owner must be on Premium or Business                                 |

## Docs site custom domain

This documentation site can also live on `docs.joinmarkt.com` via Mintlify’s custom domain (separate from storefront domains). Point a CNAME at the value Mintlify shows in the dashboard — not at `stores.joinmarkt.com`.