Custom domains
A merchant connects their own domain and their theme serves from it, with certificates handled for them.
How a request arrives
A router in front of the storefront resolves the incoming host to a tenant, then forwards to the rendering origin with the visitor’s host preserved in a forwarded header. The runtime resolves the store from that header — which is why the tenant, canonical URLs, robots and sitemap all agree on one host.
If you ever write a redirect. Behind that router, the request URL the framework sees is the origin host, not the visitor’s. A redirect built from it sends customers to the wrong domain — and any cookie you set will not come back, because it was scoped to a different origin. Always rebuild the host from the forwarded header. This is not hypothetical; it has bitten this codebase more than once.
What a theme should assume
Nothing about the host. Build internal links as relative paths and let the runtime resolve absolute URLs where they are genuinely needed — canonical tags, sitemaps, share links. A theme that hard-codes a domain breaks the moment a merchant connects theirs.