Support becomes the state machine.
- A customer sends a hostname.
- Engineering checks DNS manually.
- Certificate and proxy failures look identical.
- Renewal incidents return months later.
For SaaS product teams
Make custom domains a product feature.
Let customers launch a branded portal, workspace or storefront on a customer domain they control. Your team owns the experience; subdomain.to operates DNS verification, certificate issuance and routing.
- Customer-facing web applications
- Branded portals and workspaces
- Teams with one public HTTPS destination
Hostnameportal.acme.euVerified
DNSTLSLive
Choose your path
Start from the job your team owns.
These guides share one domain lifecycle, then focus on a different product decision.
The product problem
A simple setting hides three infrastructure lifecycles.
The customer sees a hostname field. Your team otherwise has to coordinate DNS ownership, certificate issuance and edge routing — then explain which one is blocking activation.
Your UI reflects the lifecycle.
- Create the customer-domain resource.
- Show the exact DNS instructions.
- Poll the resource and read DNS, certificate and routing statuses separately.
- Reserve webhooks for hostname creation and deletion.
Integration journey
The lifecycle your onboarding should expose.
Each state gives the customer a concrete next action instead of an open-ended “pending” message.
- 01
Create
Send the customer-owned hostname after your authorization checks.
pending_dns - 02
Instruct
Show the returned CNAME for a subdomain or A record for an apex.
pending_dns - 03
Verify
Poll GET /domains/{id} while ownership and configuration are checked.
validating - 04
Provision
DNS is accepted; certificate issuance and routing setup are progressing.
provisioning - 05
Activate
Show the branded URL only after the domain status becomes active.
active
The main sequence is pending_dns → validating → provisioning → active. Exception states are explicit: misconfigured, failed, suspended and deleting. DNS, certificate and routing statuses remain separately inspectable.
Clear boundaries
You keep the product decisions.
The integration does not replace your tenant model or authorization. It removes the infrastructure your product should not have to operate.
Your productsubdomain.to
Decide who may add or remove a domainValidate DNS ownership
Map the hostname to your customerIssue and renew certificates
Design onboarding and support copyExpose the customer domain and subsystem statuses
Serve the correct tenant from your appRoute registered hostnames only
Real integration
Start server-side, then mirror statuses in your UI.
Create customer domains from trusted application code. Store the returned identifier, poll GET /domains/{id} for activation and use webhooks only for hostname.created and hostname.deleting.
- Use an idempotency key for retries; reusing it with a different body replays the first response.
- Keep application authorization in your service.
- Do not expose a customer domain as live before its lifecycle status is active.
curl https://api.subdomain.to/v1/domains \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: acme-portal" \
-d '{
"hostname": "portal.acme.eu"
}'Product questions
Before you add the setting.
Does the customer need to move their DNS?
No. They add the record at their current DNS provider. Your UI should show the exact name and value returned for that domain.
What should support see when activation is blocked?
Show DNS, certificate and routing statuses separately, plus the expected record. That tells support whether the customer must act or the infrastructure is still progressing.
Does subdomain.to decide which tenant receives the request?
No. Your application remains responsible for resolving the registered hostname to the correct tenant and enforcing access.
What happens after the initial setup?
The certificate lifecycle and route remain managed. Your product should poll the customer-domain resource when it needs the current lifecycle status; creation and deletion webhooks do not replace that polling.