Skip to main content

​
Purpose

A Custom Domain lets your Redemption Links open on your own host name instead of AllRide’s default landing host redeem.voucher.allride.io, so your customers see a link like https://vouchers.example-transit.example.com/r/<token>.
  • Custom Domains serve only Redemption Link landing pages (purpose is always redemption-landing). The dashboards always run on AllRide host names.
  • Only consumer partners hold Custom Domains; a provider-only partner gets 403 partner-role-missing.
  • You can have at most 10 domains (excluding deleted ones).
  • AllRide provisions and renews the TLS certificate for you.
Which host a link uses: the link’s own customDomainId if that domain is active, else your default landing domain (settings.defaultLandingDomainId) if it is active, else redeem.voucher.allride.io. The landing page’s look comes from your branding (see Landing pages and custom domains).

​
Add a domain

Add a domain in the developer dashboard or with Add a custom domain. The permission manage-domains can be delegated to API keys, so an integration can provision landing domains; reading needs view-domains.
  • Use a subdomain with at least three labels. An apex domain such as example-transit.example.com answers 422 apex-domain-not-supported, because an apex cannot carry a CNAME record.
  • Host names under AllRide’s own domains answer 422 domain-not-allowed.
  • A host name that another partner already uses actively answers 409 domain-taken. Pending claims do not block each other: the first claim that becomes active wins.
  • More than 10 domains answer 422 custom-domain-limit-reached.
The response (201) is the domain with status: "pending-verification" and the DNS records to publish in verificationRecords. To use a domain for every link that does not name one, set it as your default with Update security settings (settings.defaultLandingDomainId, permission manage-settings, dashboard only). The domain must be your own and active (otherwise the constraint custom-domain-not-usable). To use a domain for single links, pass its id as customDomainId when you create a Redemption Link.

​
DNS records

Publish every record of verificationRecords at your DNS provider:
Read the domain again with Get a custom domain a few seconds after creating it: the ownership and certificate-validation records are added as soon as AllRide has registered the host name. Keep all records in place for as long as you use the domain; removing the CNAME takes the domain out of service.

​
Status and troubleshooting

  • After fixing your DNS, call Re-check a custom domain to have it checked on the next run instead of waiting; a failed domain moves back to pending-verification. The result arrives asynchronously, so poll the domain.
  • Only active domains serve traffic. Visitors of a host that is not active see a neutral “not found” page without your data.
  • lastCheckedAt shows the last check, activeLinkCount how many active links use the domain, and isDefaultLanding whether it is your default landing domain.
  • DNS changes can take a while to propagate, depending on the record’s TTL at your DNS provider.
  • Delete a custom domain when you no longer need it. Links that used it get a URL on your default landing host (or redeem.voucher.allride.io), and URLs you already shared on the deleted host stop working: check activeLinkCount first. Deleting your default landing domain clears settings.defaultLandingDomainId.
  • You receive an email when a domain becomes active, fails or is moved.