Skip to content

Checkout Purchase Domains

POST
/provider-domains/checkout-purchase

Buy one or more sending domains. SPENDS REAL CREDITS — unrestricted, same as the app; there is no per-key spend cap.

Send an Idempotency-Key header to make a retry safe (a repeat with the same key returns the original response instead of buying twice). Returns 402 if the credit hold can’t clear, 422 if the org’s plan can’t fund a purchase at all (same gate the app UI checks), 400 for a pilot-only provider or an unsupported TLD.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Buy one or more sending domains. Spends real credits — see the 402 contract on the route docstring.

object
contact_info
required

Registrant contact used for domain registration

object
key
additional properties
string
domains
required

Domains to buy, e.g. [‘acme-outreach.com’]. Up to 50 per request.

Array<string>
<= 50 items
period

Registration period, in years

integer
default: 1 >= 1
provider

Provisioning path. ‘pilot’ is limited to allowlisted orgs and otherwise returns 400.

string
default: registrar
Allowed values: registrar managed pilot
spare_domains

Extra domains bought as spare warm-up capacity (warm from day 0, excluded from sending until promoted). Up to 50 per request.

Array<string>
<= 50 items

Responses

202

Successful Response

object
data
required
object
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string