> ## Documentation Index
> Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom domains

> Serve Redemption Link landing pages on your own host name, such as vouchers.example-transit.example.com.

## 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`](https://docs-consumer.voucher.allride.io/errors/catalog#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](https://docs-consumer.voucher.allride.io/consumer/landing-pages.md)).

## Add a domain

Add a domain in the [developer dashboard](https://consumer-developers.voucher.allride.io/go/custom-domains) or with [Add a custom domain](https://docs-consumer.voucher.allride.io/api-reference/partner-custom-domains-create.md). The permission `manage-domains` can be delegated to API keys, so an integration can provision landing domains; reading needs `view-domains`.

```bash theme={null}
curl -X POST "$VOUCHER_API_BASE_URL/partner/v1/custom-domains" \
  -H "Authorization: Bearer $VOUCHER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "hostname": "vouchers.example-transit.example.com", "purpose": "redemption-landing" }'
```

* Use a **subdomain** with at least three labels. An apex domain such as `example-transit.example.com` answers `422` [`apex-domain-not-supported`](https://docs-consumer.voucher.allride.io/errors/catalog#apex-domain-not-supported), because an apex cannot carry a CNAME record.
* Host names under AllRide's own domains answer `422` [`domain-not-allowed`](https://docs-consumer.voucher.allride.io/errors/catalog#domain-not-allowed).
* A host name that another partner already uses actively answers `409` [`domain-taken`](https://docs-consumer.voucher.allride.io/errors/catalog#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`](https://docs-consumer.voucher.allride.io/errors/catalog#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](https://docs-consumer.voucher.allride.io/api-reference/partner-partner-update-settings.md) (`settings.defaultLandingDomainId`, permission `manage-settings`, dashboard only). The domain must be your own and `active` (otherwise the constraint [`custom-domain-not-usable`](https://docs-consumer.voucher.allride.io/errors/catalog#custom-domain-not-usable)). To use a domain for single links, pass its id as `customDomainId` when you [create a Redemption Link](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md).

## DNS records

Publish every record of `verificationRecords` at your DNS provider:

| `purpose` | Type | Name | Value |
| - | - | - | - |
| `routing` | `CNAME` | your host name, for example `vouchers.example-transit.example.com` | `customers.voucher.allride.io` |
| `ownership` | `TXT` | `_allride-voucher-domain.<your host name>` | the token shown in the record |
| `dcv` | as shown | as shown | as shown (certificate validation; appears a few seconds after you add the domain) |

```json theme={null}
{
  "verificationRecords": [
    { "type": "cname", "name": "vouchers.example-transit.example.com", "value": "customers.voucher.allride.io", "purpose": "routing" },
    { "type": "txt", "name": "_allride-voucher-domain.vouchers.example-transit.example.com", "value": "4f0c2b1e9d8a7c6b", "purpose": "ownership" }
  ]
}
```

Read the domain again with [Get a custom domain](https://docs-consumer.voucher.allride.io/api-reference/partner-custom-domains-get.md) 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

| `status` | Meaning |
| - | - |
| `pending-verification` | Waiting for your DNS records. AllRide checks regularly, about every 10 minutes. |
| `active` | Ownership verified, the CNAME points to AllRide and the certificate is active (`sslStatus`). Links on this host work. |
| `failed` | Verification did not succeed within **14 days**, failed with an error, or another partner's claim for the same host became active. Read `verificationErrors`. A failed domain is deleted automatically after 7 days. |
| `moved` | The domain was active, but its DNS no longer points to AllRide. It returns to `active` when you restore the records; after 7 days in `moved` it is deleted. |
| `deleted` | Deleted by you or automatically. Final. |

* After fixing your DNS, call [Re-check a custom domain](https://docs-consumer.voucher.allride.io/api-reference/partner-custom-domains-refresh.md) 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](https://docs-consumer.voucher.allride.io/api-reference/partner-custom-domains-delete.md) 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.

## Related

* [Landing pages and custom domains](https://docs-consumer.voucher.allride.io/consumer/landing-pages.md)
* [Redemption links](https://docs-consumer.voucher.allride.io/consumer/redemption-links.md)
* [Network and IP addresses](https://docs-consumer.voucher.allride.io/guides/network.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.