White label custom domains for SaaS: how to offer them

What customers want from a custom domain

Your customers want your product to look like part of their own business. In practice that means a hostname they own, in the place their users already look.

This is the mechanism explained in the white label domain guide, seen from the vendor's side. The customer adds a DNS record. You are responsible for everything else.

The five jobs behind every custom domain

A custom domain feature looks small in a design review and turns out to be five separate systems. Each has its own failure modes.

How a customer connects a domain

1. The customer enters a domain in your app, usually inside an embedded widget.
2. A pre-flight check looks up the domain's DNS provider, picks the most direct way to apply records and flags conflicts before anything is written.
3. The records are applied by one of four methods, shown in the table below.
4. Propagation is polled until every expected record resolves.
5. The connection goes live. Through the edge, the HTTPS certificate is issued on the first visit.
6. Your app is told by webhook (connection.live) and switches the tenant on.

The widget chooses the method for each domain, so you do not write a separate flow for each DNS provider. The connect flow docs describe the four methods in detail.

Where the domain points: two routing models

Every connection's records point somewhere, and you choose where once for your application. The records a customer sees, the checks and the live DNS diagnosis all follow that choice.

Through the edge, CustomDomain™ terminates TLS and proxies each request to your origin, passing the customer's hostname in X-Forwarded-Host so one origin can serve every customer. Set the default origin for your application before the first customer connects, because a request with no origin to go to is answered with a 421.

Pick the model before customers connect. Changing it later changes the records that new connections get, and records already written stay as they were until you reapply the connection.

HTTPS certificates: issuance and renewal

Through the edge, a certificate is issued the first time someone visits the domain over HTTPS after it points at CustomDomain™. It comes from Let's Encrypt. Renewal starts about 30 days before expiry and needs no access to the customer's DNS, so it works the same whatever access was kept. A failing renewal is retried after 30 minutes at first, then less often after each failure, up to about once a day, while the current certificate keeps serving.

Webhooks report issuance and renewal, and warn at 14, 7 and 3 days before a certificate that has not renewed expires. In your own infrastructure mode you issue the certificates yourself. The same rule applies: the name has to point at you before the certificate can be issued, which the challenge types explain.

White labelling the connect flow itself

The widget is the part of the process that customers see, so it should look like your product. The whiteLabel configuration covers colors, font, corner radius, light and dark logos, around 90 design tokens, per screen switches and 13 languages. Removing the CustomDomain™ branding and using the full white label configuration are Enterprise features, so check pricing for what your plan includes.

Build or buy

Building it yourself is reasonable when you have a handful of customers on one DNS provider and an engineer who is comfortable with certificates. It stops being reasonable when every new customer brings a new DNS host and a new way to get a record wrong. Let's Encrypt publishes issuance rate limits worth reading before you commit to the DIY route.

What it costs

Each hostname counts once as a connection. Prices below were checked on October 7, 2026. The pricing page is the source of truth, and every self-serve plan starts with a 14 day free trial. The card is added at checkout and the first charge comes when the trial ends.

Launch checklist for software teams

• Pick the hostname pattern you will recommend, such as app.customer.com, and put it in your docs. Offer a subdomain first, and steer root domains to www where the DNS provider has no ALIAS style record.
• Choose the edge or your own infrastructure before the first customer connects, and set the default origin so requests are not answered with a 421.
• Look up the tenant by the host the customer used (the Host header, or X-Forwarded-Host behind a proxy), not by a path or a subdomain of your own domain.
• Scope cookies and sessions per host, and add each custom host to the origins your CSRF and CORS checks allow.
• Build canonical URLs, sitemaps and outbound links from the tenant's host, so search engines and email links agree on one address.
• Listen for webhooks such as connection.live and the certificate events, and show the customer the state of their domain.
• Decide what happens when a customer leaves: remove the domain, and tell them to delete the DNS record.

Most failed connections trace back to a short list of DNS and HTTPS causes. The white label domain troubleshooting guide lists them with the commands to run, and the free Domain Health Check tests a domain in one step.