Setting up a custom domain

By default, Chargebee Growth hosts your cancel experience on a Chargebee domain. You can configure a custom domain to provide a branded experience for your users.

When a custom domain is configured, users see your domain (for example, cancel.example.com) instead of a Chargebee-hosted URL.

You can manage multiple custom domains for your company and assign them to specific applications. This lets you use different branded URLs for different apps—for example, one domain for your test app and another for your live app—instead of sharing a single company-wide domain.

Before you begin

Before you configure a custom domain, make sure that you have:

• Access to your DNS provider.
• Permission to create and update DNS records, such as CNAME and, optionally, CAA records.
• Access to Settings > Custom domain in Chargebee Growth.

How domain assignment works

Chargebee Growth resolves which domain to use for a retention session in this order:

1. Brand domain (multi-brand companies only): If the session resolves to a brand that has its own domain, that brand domain is used.
2. Application domain: If the application has a custom domain assigned, that domain is used.
3. Company default domain: If the application has no domain assignment, the company default (company-wide) domain is used.

If you deactivate a domain that applications were using, those applications fall back to the company default domain.

Configuring a custom domain

To set up a custom domain, complete the following steps.

1. Go to Settings > Custom domain.

2. Create a new domain (or open an existing domain) and enter the subdomain you want to use, for example, cancel.example.com or cancel-test.example.com.

3. In your DNS provider, create a CNAME record with the following values:

   • Host / Name: the subdomain label (for example, cancel or cancel-test)
   • Destination / Target: custom.prod.brightback.com

   This maps your domain to the Growth experience.

4. Return to the Custom domain page and submit the domain for verification. Chargebee Growth validates your DNS configuration, SSL certificate setup, and domain reachability. You receive a confirmation email once the domain is ready.

5. After verification succeeds, activate the domain so it can be used.

6. Optionally, open the domain details and assign one or more applications to that domain. Leave applications unassigned if they should continue to use the company default domain.

7. Set one domain as the company default (company-wide) domain. Unassigned applications and fallback routing use this domain.

Repeat these steps for each additional domain you need—for example, a separate domain for your test application and another for your live application.

Assign domains to applications

Use application assignment when you need different branded URLs per app (for example, test versus live):

1. Go to Settings > Custom domain.
2. Open the domain that should serve a specific application (or applications).
3. Assign the application(s) to that domain and save.
4. Leave applications that should keep the company default domain unassigned.
5. Start a test cancel or pre-cancel session for each application and confirm the session URL uses the expected domain.

How custom domain routing works

When a user visits your custom domain, your DNS configuration routes the request to the Growth infrastructure while preserving your branded URL:

cancel.example.com → custom.prod.brightback.com

DNS propagation

DNS changes are not always immediate. Keep the following timings in mind after you create or update your records:

• DNS changes can take up to 24 hours to propagate.
• Changes often take effect within 1–2 hours.
• The recommended TTL is 300 seconds.

Troubleshoot verification failures

If verification fails, review the following common issues.

CNAME or DNS record is not configured correctly

Make sure that:

• The CNAME record exists.
• The destination is exactly custom.prod.brightback.com.

Invalid domain format

Enter a valid subdomain, such as cancel.example.com. The following formats are not valid:

• http://cancel.example.com
• cancel

Connection or SSL issues

The following errors usually indicate a DNS propagation delay or an SSL handshake issue:

• connect_timeout
• io_exception
• non_200_status

If you see these errors, wait for DNS to finish propagating and then try again.

Certificate issues

• certificate_expired: Renew the certificate.
• expected_certificate_authority_not_found: Make sure that Let's Encrypt is allowed to issue certificates for your domain. See Configure a CAA record.

Configure a CAA record (advanced)

If your domain uses CAA records, you must allow Let's Encrypt to issue certificates for it.

Example CAA record

example.com. 1800 IN CAA 0 issue "letsencrypt.org"

Check your existing CAA records

To check the CAA records for your domain, run:

dig +noall +answer example.com caa

Allow Let's Encrypt when a CAA record exists

If a CAA record is already configured, use one of the following options:

• Update the root domain: Add letsencrypt.org as an allowed certificate authority on your root domain.
• Use a subdomain: Create a subdomain with its own CAA record and use it for your custom domain, for example, cancel.subzone.example.com.

Verification error reference

For persistent issues, contact growth-support@chargebee.com.

Additional resources

For provider-specific guidance on creating DNS records, see:

• Rackspace
• GoDaddy
• Hover
• Bluehost