Your first request#
Check availability and pricing for a name across two TLDs:{
"message": "Available domains",
"data": {
"exactMatch": {
"domainName": "example.com",
"status": "AVAILABLE",
"domainPrice": "14.39",
"renewPrice": "16.79"
},
"availableDomains": [
{
"domainName": "example.org",
"status": "AVAILABLE",
"domainPrice": "42.00",
"renewPrice": "45.00"
}
]
}
}
Prices come back already resolved through your own pricing book - the margin, promo and override configuration on your account - so they are the retail figures you can show a customer directly.Then register it, for a customer you create inline:Registration is synchronous: the response already carries the final result. 201 means orderStatus: "SUCCESS" - the domain is registered. 200 means orderStatus: "FAILED", with the reason in data.error. No webhook or polling is needed for this call's own outcome - that's only for the bulk endpoint, where registration is genuinely async. GET /whoami returns the account a key belongs to and the scopes it carries, which is the quickest way to confirm a key is wired up correctly.Reuse a customer instead of creating one inline#
The newCustomer block above creates the customer inline, which keeps a first request down to a single call. Don't build on that pattern: newCustomer does no de-duplication, not even on email, so sending it again for the same person creates a second, unrelated customer record - and that person's domains end up split across two customers that the API has no way to reconcile.For anything beyond a first test, create each customer once with POST /customers (the same fields as newCustomer, flat at the top level rather than nested):{
"status": 201,
"message": "Customer created",
"data": { "id": "b2a1c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" }
}
Store that data.id against the customer in your own system, then send it as userId on every later purchase in place of newCustomer - the two are mutually exclusive, and sending both fails with 422:{
"domain": { "domainName": "example.com", "years": 1, "autoRenew": true },
"userId": "b2a1c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"collectionMethod": "MANUAL"
}
Creating the customer up front has two other benefits. It puts a billing address on file, which registration requires - POST /domain/register fails with 425 for a customer who has none. And it is the same id every other customer endpoint takes, so GET /customers/{id}, PATCH /customers/{id}/billing and GET /domains?userId= all work against it immediately.One thing to know when reusing an id: a customer can only have one domain order in flight at a time. While an earlier order for that customer is still unresolved, further registrations for them fail with 400 ("Your previous domain order is already in progress") for up to 15 minutes. To buy several domains for one customer, send them in a single POST /domain/register/bulk call rather than looping over POST /domain/register.Registration is synchronous: the response already carries the final result. 201 means orderStatus: "SUCCESS" - the domain is registered. 200 means orderStatus: "FAILED", with the reason in data.error. No webhook or polling is needed for this call's own outcome - that's only for the bulk endpoint, where registration is genuinely async. GET /whoami returns the account a key belongs to and the scopes it carries, which is the quickest way to confirm a key is wired up correctly.Modified at 2026-10-22 09:07:31