A custom domain serves Flint-hosted checkout or the Flint-hosted customer account on a hostname you own, such as pay.example.com or account.example.com. Each one has a custom_domain_id beginning with cdom_, a type of checkout or customer_account, the DNS records to publish, and a status that moves from provisioning to active. The Custom domains guide covers DNS setup, status reasons, redirects, and the add-on in full.
Manage custom domains#
Listing and getting custom domains requires settings.read. Creating, checking, and archiving them requires settings.write. Each environment has its own custom domains, and an ID from another environment returns 404 RESOURCE_NOT_FOUND, the same as an unknown ID. Creating a domain needs the custom domain add-on, and a checkout domain needs a live key.
curl -X POST https://api.withflintpay.com/v1/custom-domains \
-H "Authorization: Bearer YOUR_LIVE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "customer_account", "hostname": "account.example.com" }'
An environment has at most one custom domain of each type that isn't archived. Creating another returns 409 ALREADY_EXISTS with param type, and details[0].current_resource is the existing domain. A domain's hostname can't change: archive the domain and create a new one. A customer_account domain needs customer_account.mode flint_hosted; with merchant_hosted, creating one returns 409 ACTION_NOT_ALLOWED with details[0].reason customer_account_mode_conflict.
GET /v1/custom-domains returns domains newest first, ordered by created_at and then custom_domain_id, both descending. Set page_size from 1 to 100, with 20 returned by default, and pass next_page_token as the next request's page_token. Filter with type and status, each taking one or more values. Archived domains are left out unless status names archived. GET /v1/custom-domains/{custom_domain_id} returns any domain, including an archived one.
If the create response is lost and a retry returns 500 IDEMPOTENCY_RECOVERY_REQUIRED, keep the original Idempotency-Key. List domains with GET /v1/custom-domains?type=customer_account and GET /v1/custom-domains?type=customer_account&status=archived, using type=checkout for both requests if that was the original type. Follow pagination and inspect current and archived domains for the requested hostname; use a matching domain's custom_domain_id to retrieve its current state. Do not switch keys or wait for key retention to expire to create again. Contact support with the request_id if the outcome is still unclear.
POST /v1/custom-domains/{custom_domain_id}/validate checks the DNS records and certificate again now. Send no body or an empty JSON object. Each domain can be checked once every 60 seconds; a sooner request returns 429 RATE_LIMIT_EXCEEDED with Retry-After. Checking an archived domain returns 409 ACTION_NOT_ALLOWED with details[0].reason archived.
Archive a custom domain#
DELETE /v1/custom-domains/{custom_domain_id} archives the domain. New links use Flint's address right away, and requests to the hostname redirect to Flint's address until redirect_expires_at, at most 30 days after archiving. Once archived, dns_records lists the records you can delete. Archiving an archived domain returns it unchanged. An archived domain can't be restored; create a new domain to use the hostname again.
While a customer_account domain isn't archived, PATCH /v1/settings refuses to set customer_account.mode to merchant_hosted or to send "customer_account": null, with 409 RESOURCE_IN_USE. details[0].blocking_resources names the domain.
Status changes#
custom_domain.status_changed sends the custom domain, the same object GET /v1/custom-domains/{custom_domain_id} returns, each time its status changes, including when it's archived. status_reason is null while the domain is active and once it's archived. active_payment_attempt_count is set on checkout domains and null on customer account domains.