Create Registration
Starts a domain registration workflow. This is a billable operation — successful
registration charges the account’s default payment method. All successful
domain registrations are non-refundable — once the workflow completes with
state: succeeded, the charge cannot be reversed.
Prerequisites
- The account must have a billing profile with a valid default payment method.
Set this up at
https://dash.cloudflare.com/{account_id}/billing/payment-info. - The account must not already be at the maximum supported domain limit. A single account may own up to 100 domains in total across registrations created through either the dashboard or this API.
- The domain must be on a supported extension for programmatic registration.
- Use
POST /domain-checkimmediately before calling this endpoint to confirm real-time availability and pricing.
Supported extensions
In this API, “extension” means the full registrable suffix after the domain
label. For example, in example.co.uk, the extension is co.uk.
Programmatic registration is currently supported for:
com, org, net, app, dev, cc, xyz, info, cloud, studio,
live, link, pro, tech, fyi, shop, online, tools, run,
games, build, systems, world, news, site, network, chat,
space, family, page, life, group, email, solutions, day,
blog, ing, icu, academy, today
Cloudflare Registrar supports 400+ extensions in the dashboard. Extensions
not listed above can still be registered at
https://dash.cloudflare.com/{account_id}/domains/registrations.
Express mode
The only required field is domain_name. If contacts is omitted, the system
uses the account’s default address book entry as the registrant. If no default
exists and no contact is provided, the request fails. Set up a default address
book entry and accept the required agreement at
https://dash.cloudflare.com/{account_id}/domains/registrations.
Defaults
years: defaults to the extension’s minimum registration period (1 year for most extensions, but varies — for example,.ai(if supported) requires a minimum of 2 years).auto_renew: defaults tofalse. Setting it totrueis an explicit opt-in authorizing Cloudflare to charge the account’s default payment method up to 30 days before domain expiry to renew the registration. Renewal pricing may change over time based on registry pricing.privacy_mode: defaults toredaction.
Premium domains
Premium domain registration is not currently supported by this API.
If POST /domain-check returns tier: premium, do not call this
endpoint for that domain.
Response behavior
By default, the server holds the connection for a bounded, server-defined
amount of time while the registration completes. Most registrations finish
within this window and return 201 Created with a completed workflow status.
If the registration is still processing after this synchronous wait window,
the server returns 202 Accepted. Poll the URL in links.self to track progress.
To skip the wait and receive an immediate 202, send Prefer: respond-async.
Security
API Token
The preferred authorization scheme for interacting with the Cloudflare API. Create a token.
API Email + API Key
The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.
The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.
Parameters
Fully qualified domain name (FQDN) including the extension
(e.g., example.com, mybrand.app). The domain name uniquely
identifies a registration — the same domain cannot be registered
twice, making it a natural idempotency key for registration requests.
Enable or disable automatic renewal. Defaults to false if omitted.
Setting this field to true is an explicit opt-in authorizing
Cloudflare to charge the account’s default payment method up to 30
days before domain expiry to renew the domain automatically.
Renewal pricing may change over time based on registry pricing.
WHOIS privacy mode for the registration. Defaults to redaction.
off: Do not request WHOIS privacy.redaction: Request WHOIS redaction where supported by the extension. Some extensions do not support privacy/redaction.
Number of years to register (1–10). If omitted, defaults to the
minimum registration period required by the registry for this
extension. For most extensions this is 1 year, but some extensions
require longer minimum terms (e.g., .ai requires a minimum of
2 years).
The registry for each extension may also enforce its own maximum registration term. If the requested value exceeds the registry’s maximum, the registration will be rejected. When in doubt, use the default by omitting this field.
Create Registration
import os
from cloudflare import Cloudflare
client = Cloudflare(
api_token=os.environ.get("CLOUDFLARE_API_TOKEN"), # This is the default and can be omitted
)
workflow_status = client.registrar.registrations.create(
account_id="023e105f4ecef8ad9ca31a8372d0c353",
domain_name="my-new-startup.com",
)
print(workflow_status.completed){
"errors": [
{
"code": 1000,
"message": "message",
"documentation_url": "documentation_url",
"source": {
"pointer": "pointer"
}
}
],
"messages": [
{
"code": 1000,
"message": "message",
"documentation_url": "documentation_url",
"source": {
"pointer": "pointer"
}
}
],
"result": {
"completed": false,
"created_at": "2019-12-27T18:11:19.117Z",
"links": {
"self": "/accounts/{account_id}/registrar/registrations/example.com/registration-status",
"resource": "/accounts/{account_id}/registrar/registrations/example.com"
},
"state": "in_progress",
"updated_at": "2019-12-27T18:11:19.117Z",
"context": {
"foo": "bar"
},
"error": {
"code": "registry_rejected",
"message": "Registry rejected the request."
}
},
"success": true
}{
"errors": [
{
"code": 10000,
"message": "Domain limit reached: you cannot register more than 100 domains.",
"source": {
"pointer": "/domain_name"
}
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "domain_name is required",
"source": {
"pointer": "/domain_name"
}
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "Must be a boolean",
"source": {
"pointer": "/auto_renew"
}
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "No registrant contact provided and no default address book entry found for this account."
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "Registration is not supported for this extension"
}
],
"messages": [],
"result": null,
"success": false
}Returns Examples
{
"errors": [
{
"code": 1000,
"message": "message",
"documentation_url": "documentation_url",
"source": {
"pointer": "pointer"
}
}
],
"messages": [
{
"code": 1000,
"message": "message",
"documentation_url": "documentation_url",
"source": {
"pointer": "pointer"
}
}
],
"result": {
"completed": false,
"created_at": "2019-12-27T18:11:19.117Z",
"links": {
"self": "/accounts/{account_id}/registrar/registrations/example.com/registration-status",
"resource": "/accounts/{account_id}/registrar/registrations/example.com"
},
"state": "in_progress",
"updated_at": "2019-12-27T18:11:19.117Z",
"context": {
"foo": "bar"
},
"error": {
"code": "registry_rejected",
"message": "Registry rejected the request."
}
},
"success": true
}{
"errors": [
{
"code": 10000,
"message": "Domain limit reached: you cannot register more than 100 domains.",
"source": {
"pointer": "/domain_name"
}
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "domain_name is required",
"source": {
"pointer": "/domain_name"
}
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "Must be a boolean",
"source": {
"pointer": "/auto_renew"
}
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "No registrant contact provided and no default address book entry found for this account."
}
],
"messages": [],
"result": null,
"success": false
}{
"errors": [
{
"code": 10000,
"message": "Registration is not supported for this extension"
}
],
"messages": [],
"result": null,
"success": false
}