Register a domain
Charges your wallet for the years asked for, plus WHOIS privacy for those years when it is on. Send an Idempotency-Key header so a retry can never register twice. The registrar can answer pending: the domain comes back with status: "pending" and the charge stays held until it finishes. A coupon is checked before the registrar is asked, so an order it cannot be used on is refused with nothing registered, unless you send couponOptional.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
Idempotency-Key?stringA value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again.
8 <= length <= 200application/json- body
domain*string3 <= length <= 253years?integerHow many years. Defaults to 1
1 <= value <= 10customerId*stringRequired: every purchase belongs to one of your customers
contact?Who to register the domain to, for this order alone. A registrant is required: send one here, or store one on the customer, or set a default registrant in your account settings. Absent, it falls back to the customer's registrant, then your account's default
registrant?stringWhich stored contact to register to instead of a one-off contact: the named customer's own registrant, or your account's default registrant. Sending it with contact is refused, as is naming one that is not stored
"customer""default"privacy?booleanAdd WHOIS privacy. Absent, your account's default decides. An ending that does not offer privacy is refused
coupon?stringA coupon code, unlocking the promotion it belongs to for this registration. A promotion everyone on the list gets needs no code
1 <= length <= 40couponOptional?booleanPlace the order at the normal price when the coupon cannot be used, instead of refusing it
falseCreated
application/json- response
Created
id*stringdomain*stringstatus*stringpending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours
"pending""pending_validation""active""expired""redemption""needs_reconciliation""transferred_out""deleted"customerId*|The customer this was bought for, if any
unitPrice*integerPrice per year, in minor units
0 <= valuecustomerPrice*|A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none
paidTotal*integerEverything charged for this domain so far, in minor units
0 <= valueregisteredAt*stringdate-timeexpiresAt*stringWhen the registration ends. While status is pending or needs_reconciliation this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes
date-timenameservers*array<>Where the domain's DNS is served from
customNameservers*booleanFalse while the domain is on the registrar's own nameservers
contact*|The registrant, or null until you set one
contacts*The administrative, technical and billing contacts. null means the same as the registrant
locked*booleanWhether transfers away from us are refused
suspended*booleanWhether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews
privacy*booleanWhether WHOIS privacy is on for this domain
privacyPrice*|What you pay per year for privacy while it is on, in minor units. Null when privacy is off
autoRenew*booleanWhether this domain renews itself from your wallet shortly before it expires
dns*Hosted DNS and DNSSEC for this domain. Every field is always there
actor*|Who placed this order
curl -X POST "https://example.com/v1/domains" \ -H "Idempotency-Key: 2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11" \ -H "Content-Type: application/json" \ -d '{ "domain": "northwind-telecom.com", "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA" }'{ "id": "dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "domain": "northwind-telecom.com", "status": "pending", "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "unitPrice": 1440, "customerPrice": null, "paidTotal": 1440, "registeredAt": "2026-10-07T11:04:31.000Z", "expiresAt": "2027-10-07T11:04:31.000Z", "nameservers": [ "ns1.example-dns.com" ], "customNameservers": true, "contact": { "name": "Jo Bloggs", "organization": "Northwind Telecom", "email": "[email protected]", "phone": "+1 415 555 0132", "address": "1 Market Street", "city": "San Francisco", "state": "CA", "postalCode": "94105", "country": "US", "validation": "pending" }, "contacts": { "admin": null, "tech": null, "billing": null }, "locked": true, "suspended": true, "privacy": true, "privacyPrice": null, "autoRenew": true, "dns": { "supported": true, "hosted": true, "dnssecSupported": true, "signed": true, "dsRecords": [ { "keyTag": 0, "algorithm": 0, "digestType": 0, "digest": "49FCE7" } ], "keys": [ { "flags": 256, "algorithm": 0, "publicKey": "string" } ] }, "actor": { "kind": "user", "label": "string" }}