---
title: "Register a domain."
method: POST
path: "/v1/domain-purchases"
tags: ["Domain purchases"]
---

# Register a domain.

`POST /v1/domain-purchases`

## Request

- Base URL: `https://api.domainee.dev`
- URL: `https://api.domainee.dev/v1/domain-purchases`
- Auth: HTTP bearer

Charges the workspace and registers the domain in one call. If the registrar
refuses after the charge clears, the charge is refunded automatically and the
purchase comes back `failed`.

Send `maxTotalCents` to refuse the purchase if the price moved since your quote,
and `autoConnect` to attach the new domain to an origin without a second call.
Send an `Idempotency-Key` — this endpoint moves money.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `hostname` string, required
  - `years` integer
  - `registrant` Registrant, required: ICANN-required owner contact. Sent to the registrar verbatim.
    - `firstName` string, required
    - `lastName` string, required
    - `email` string, email, required
    - `phone` string, required: E.164 with a dot after the country code.
    - `address1` string, required
    - `address2` string
    - `city` string, required
    - `stateOrProvince` string, required
    - `postalCode` string, required
    - `country` string, required: ISO 3166-1 alpha-2.
    - `organization` string
  - `enableWhoisPrivacy` boolean: Rejected with a 400 on TLDs that do not support it.
  - `autoRenew` boolean
  - `maxTotalCents` integer: Abort with `price_changed` if the total would exceed this.
  - `customerReference` string
  - `autoConnect` object: Connect the domain to an origin as soon as it registers.
    - `originUrl` string, uri, required
    - `keepHost` boolean

## Response `201`

The purchase.

- object
  - `purchase` DomainPurchase, required: A domain registered through Domainee on the customer's behalf.
    - `id` string, required
    - `workspaceId` string, required
    - `hostname` string, required
    - `years` integer, required
    - `wholesaleCents` integer: Registrar cost at purchase time.
    - `feeCents` integer: Domainee's per-purchase fee.
    - `totalCents` integer: What the workspace was charged.
    - `currency` 'USD'
    - `registrar` 'namecheap'
    - `registrarDomainId` string, nullable
    - `status` 'pending' | 'completed' | 'failed' | 'refunded', required: `pending` means the charge cleared but the registration is not confirmed yet; a failed registration is refunded automatically.
    - `errorMessage` string, nullable
    - `registrant` object: Minimal owner snapshot. The registrar remains the source of truth.
      - `firstName` string
      - `lastName` string
      - `email` string, email
      - `country` string: ISO 3166-1 alpha-2.
    - `whoisPrivacyEnabled` boolean
    - `autoRenew` boolean
    - `expiresAt` string, date-time, nullable
    - `connectedDomainId` string, nullable: Set when the purchase was auto-connected to a /v1/domains entry.
    - `customerReference` string, nullable: Opaque caller-supplied reference, echoed on reads and webhooks.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time

## Other responses

- `400`: The request body or query failed validation.
- `401`: Missing, malformed, revoked, or expired Bearer token.
- `402`: The workspace has no active subscription or the charge failed.
- `409`: `unavailable` — the domain was taken; `price_changed` — the total exceeded `maxTotalCents`.
- `502`: The registrar rejected the registration. Any charge was refunded.

---

[API](https://skmtc.dev/domainee/apis/domainee-api.md) · [All operations](https://skmtc.dev/domainee/apis/domainee-api/llms.txt) · [OpenAPI document](https://skmtc.dev/domainee/apis/domainee-api/revisions/756d54434372?raw)