Buy a domain

Purchase a new custom domain for your company. The endpoint looks up Vercel availability and price, deducts the yearly cost (in cents) from your company credits, and registers the domain with Vercel. DNS records are configured automatically by a background job once you assign the domain to a location.

Required scope

The access token must carry this scope. A token missing it gets 403 Forbidden. Grant them to an API client under Dev Tools → API, to an assistant or CLI sign-in when you approve or edit it under Dev Tools, and to a teammate under Employee → Permissions.

domains:write

Request Body

Property	Type	Required	Description
`domain`	string	Required	Fully-qualified domain name to purchase.
`expectedPriceMax`	number	Optional	Maximum acceptable yearly price in cents. If the actual price exceeds this value, the request fails before any charge is made. Guard against TLD price changes.

POSTExample request

curl

curl -X POST "https://www.pxb.app/api/public/v1/domains" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "expectedPriceMax": 5000
  }'

200Example response

json

{
  "message": "Domain purchased successfully! DNS records will be configured automatically once you assign the domain to a location.",
  "content": {
    "domain": {
      "id": "dom_123",
      "name": "example.com"
    },
    "pricePaid": 1200
  }
}

403Example response

json

{
  "message": "Forbidden",
  "err": "Domain price exceeds the API purchase limit ($500). Please contact support to complete this purchase."
}

409Example response

json

{
  "message": "Conflict",
  "err": "Domain is not available for purchase."
}

In the console

The same thing done by hand, for anyone comparing the API against the screen they already use.

Domains

/domains

Search for a domain and purchase it.