# Custom domains

URL: https://qrdx.dev/docs/custom-domains
Source: https://github.com/qrdxinc/qrdx/blob/main/apps/docs/content/docs/custom-domains.mdx

Serve your dynamic QR codes' short links and hosted pages from a domain you own, such as go.yourbrand.com.

By default a [dynamic QR code](https://qrdx.dev/docs/dynamic-qr-codes) encodes a short link such as `https://qrdx.dev/q/aB3dE5f`. With a custom domain it encodes `https://go.yourbrand.com/aB3dE5f` instead, so people see your brand before they scan. Redirects, editing and scan analytics work the same way. Use one when the link itself is printed, or when your brand should be the only name on the pack.

**Pro and Business**

Custom domains are part of Pro (up to 5 per workspace) and Business (up to 25). See [Plans and limits](https://qrdx.dev/docs/plans-and-limits).

In a hurry? The short task page: [Use your own domain](https://qrdx.dev/docs/help/domains/custom-domains).

## How it works [#how-it-works]

You point a domain (usually a subdomain like `go.yourbrand.com`) at QRdx with a DNS record and prove you own it. From then on QRdx answers requests for that host name with your workspace's codes and pages, and nothing else. The domain belongs to the workspace it was added in: owners and admins add, verify and remove it, and every member can use it for their codes.

## Connect a domain [#connect-a-domain]

1. Open **Settings** → **Domains** in the workspace and enter the domain, for example `go.yourbrand.com`. A subdomain works best, because your main website stays where it is.
2. Add the DNS records shown for the domain at your DNS provider (where you bought the domain, Cloudflare, or wherever its DNS lives):
   - a subdomain gets a `CNAME` record,
   - a root domain (`yourbrand.com`) gets an `A` record,
   - a `TXT` record is shown too when ownership has to be confirmed.

   Copy the exact values from the dashboard. Most providers want only the part before your domain as the name (`go`, or `@` for the root).
3. Click **Verify**. DNS changes usually show up within minutes but can take up to 48 hours, so try again later if the records aren't found yet.

![The Custom domains page: a verified domain, qr.harborlane.example, with its DNS records available to show, a Check DNS button and the Add domain button.](https://qrdx.dev/docs-static/shots/custom-domains.light.webp)

Once verified, the domain appears in the **Short link domain** picker when you create or edit a dynamic code. Verified domains stay verified until you remove them, and **Check DNS** re-reads the records any time.

A domain that isn't verified within 3 days can be added by another account, so nobody can hold on to a domain they don't control.

## One-click DNS setup

Some DNS providers support [Domain Connect](https://www.domainconnect.org), an open standard that lets a service add its records for you. When your provider supports it and offers QRdx's setup, a domain waiting for DNS shows a **Set up with …** button named after your provider.

1. Click the button. Your DNS provider opens and lists the records QRdx needs.
2. Sign in there if asked, and approve the change. Nothing changes until you do.
3. You come back to the Domains page, which checks DNS right away and again over the next half minute.

The button appears only for subdomains such as `go.yourbrand.com`, and only when your provider can add exactly the records shown. Otherwise add the records from the table yourself, as above.

## Use it for codes [#use-it-for-codes]

- **New code:** pick the domain in **Short link domain** before you create the code.
- **Existing code:** choose the domain in **Edit link**, save, and download the QR code again, because the encoded link changes.

![The Edit dynamic QR code dialog with the Short link domain list open: the default qrdx.dev/q/ and the workspace's verified custom domain.](https://qrdx.dev/docs-static/shots/short-link-domain-picker.light.webp)

Every code also keeps working at its default `https://qrdx.dev/q/<slug>` link, so QR codes you printed before moving a code to your domain never break. Moving a code from one custom domain to another (or back to the default) does break QR codes printed with the old custom-domain link; the dialog warns you before you save.

### Your own back-halves [#your-own-back-halves]

On Pro and Business you can choose a code's [back-half](https://qrdx.dev/docs/dynamic-qr-codes#custom-back-halves) on your domain, such as `go.yourbrand.com/spring-menu`. It only has to be unique on that domain, so another QRdx customer using `spring-menu` doesn't matter, and only a few technical words (`api`, `_next`, `null`, `undefined`) are reserved there. A back-half chosen on your domain belongs to it and has no `qrdx.dev/q/` link. Moving such a code to another domain keeps the back-half when it's free there; moving it back to the default link keeps it when it's free on `qrdx.dev`, otherwise the code gets a new generated one.

## What the domain serves [#what-the-domain-serves]

- `https://go.yourbrand.com/<slug>` redirects for codes that use that domain. Codes on other domains, or on the default link only, show a "not found" page there.
- `https://go.yourbrand.com/p/<slug>` serves your [hosted pages](https://qrdx.dev/docs/landing-pages), with their forms, calendar files and **Save contact** downloads.
- `https://go.yourbrand.com/01/<GTIN>` ([GS1 Digital Link](https://qrdx.dev/docs/product-pages#gs1-digital-link)) opens the product page with that GTIN whose code uses the domain.
- On Business, `https://go.yourbrand.com/stats/<token>` serves the [client reports](https://qrdx.dev/docs/client-reports) you assigned to the domain.
- `https://go.yourbrand.com/` shows a small page saying the domain hosts QR code links. Every other path returns "not found": the domain never serves the dashboard, the editor or any other part of QRdx.

A domain that isn't verified yet shows "This domain isn't connected yet" instead. Changes (a newly verified or removed domain) take up to a minute to reach every server.

## Limits and plans [#limits-and-plans]

| | Free | Pro | Business |
| --- | --- | --- | --- |
| Custom domains per workspace | None | 5 | 25 |
| Client reports on your domain | No | No | Yes |

Downgrading never breaks anything: verified domains keep serving the codes that use them. Without Pro or Business you can't add or verify domains or move more codes onto one, but you can still edit those codes and remove domains.

Removing a domain switches its codes back to their default `qrdx.dev/q/<slug>` link. Back-halves chosen on the domain move to `qrdx.dev` when they're free there; the others get a new generated back-half. QR codes printed with the custom-domain link stop working, so the dialog shows how many codes use the domain first.

## For developers [#for-developers]

The [codes API](https://qrdx.dev/docs/developers/api/create-codes) accepts `domainId` (the id of a verified domain in the same workspace) on `POST /v1/codes` and `PATCH /v1/codes/{id}`. Send `"domainId": null` in a `PATCH` to switch back to the default link. Moving a code onto a domain needs Pro or Business and returns `402 PLAN_REQUIRED` otherwise.

Each code in a response includes:

| Field | Description |
| --- | --- |
| `shortLink` | The link to encode: on the custom domain once it is verified |
| `defaultShortLink` | `https://qrdx.dev/q/<slug>`, which always works; `null` for a back-half chosen on the custom domain |
| `domain` | `{ "id", "hostname", "verified" }`, or `null` |

## Self-hosting [#self-hosting]

How domains get connected depends on your deployment:

- **On Vercel:** set `VERCEL_API_TOKEN` (a token with access to the project), `VERCEL_PROJECT_ID` and, for a team project, `VERCEL_TEAM_ID`. Domains are then added to the project through the Vercel Domains API, which also issues the TLS certificates. Without these variables the Domains page explains that custom domains aren't set up, because Vercel only routes domains that were added to the project.
- **Anywhere else** (Docker, Node.js): leave those variables unset. Domains are verified manually:
  1. Point the domain at your server with a `CNAME` (to your app's host name) or an `A` record (your server's IP).
  2. Make your reverse proxy accept the domain, serve HTTPS for it (for example with Caddy's on-demand TLS or a certbot certificate), and forward the original `Host` header to the app. With nginx that's `proxy_set_header Host $host;`; Caddy does it by default.
  3. Add the domain on the Domains page, create the `TXT` record it shows (`_qrdx-challenge.<your-domain>` with the value `qrdx-verify=<token>`), and click **Verify**. The app checks the record with a DNS lookup.

**One-click DNS setup** (optional) uses [Domain Connect](https://www.domainconnect.org). It needs a template of your own, accepted by each DNS provider you want to support, and an RSA key that signs the setup links: set `DOMAIN_CONNECT_PROVIDER_ID`, `DOMAIN_CONNECT_SERVICE_ID` and `DOMAIN_CONNECT_PRIVATE_KEY` (PEM), and publish the public key as `TXT` records at `_dck1.<provider id>`. QRdx's own template (`domain-connect/` in the repository) works only for qrdx.dev, because providers check the signature against its key. Until the published key matches, no button is shown and the app logs why.

The app recognizes custom domains by the `Host` header. Requests for your own app URL, `NEXT_PUBLIC_SHORT_LINK_BASE_URL`, `localhost` and `*.vercel.app` are always treated as the main app. See [Self-hosting](https://qrdx.dev/docs/self-hosting#optional-services).

## Related [#related]

- [Use your own domain](https://qrdx.dev/docs/help/domains/custom-domains)
- [Dynamic QR codes](https://qrdx.dev/docs/dynamic-qr-codes#custom-back-halves): custom back-halves
- [Product pages and GS1 Digital Link](https://qrdx.dev/docs/product-pages#gs1-digital-link)
- [Client reports](https://qrdx.dev/docs/client-reports): branded stats pages on your domain
