---
title: "Purchase a domain"
method: POST
path: "/domains/buy"
---

# Purchase a domain

`POST /domains/buy`

## Request

- Base URL: `https://namemy.app/api/v1`
- URL: `https://namemy.app/api/v1/domains/buy`
- Auth: HTTP bearer

Purchase a domain for one year using the user's saved payment method.
Requires `domains:write` permission.

Requires a WHOIS registrant contact: pass `contact`, or save one at
https://namemy.app/app/settings first. Without either the call fails
with `contact_required` and lists the `missing` fields.

The flow places a hold on the saved card, provisions the domain,
then captures payment. If provisioning fails, the hold is released.

## Request body

- object
  - `domain` string, required: Domain to purchase
  - `contact` ContactInput
    - `firstName` string
    - `lastName` string
    - `email` string
    - `phone` string
    - `address1` string
    - `address2` string
    - `city` string
    - `state` string
    - `zip` string
    - `country` string: 2-letter ISO code
    - `organization` string
  - `privacy` boolean: Enable WHOIS privacy
  - `autoRenew` boolean
  - `emailForwards` object[]
    - `from` string
    - `to` string

## Response `200`

Purchase successful

- object
  - `success` boolean
  - `domain` string
  - `registrar` string
  - `retailPrice` number
  - `currency` string
  - `paymentIntent` string
  - `provisioning` object[]
    - `step` string
    - `success` boolean
    - `message` string
  - `elapsedMs` integer

## Other responses

- `400`: `invalid_domain`, `years_unsupported` (any `years` other than 1), `contact_required` (with `missing` and `hint`), `invalid_contact` (with `fieldErrors`), `domain_unavailable`, or `registration_failed` (with `provisioningSteps`; nothing charged).
- `401`: Missing or invalid API key
- `402`: `payment_method_required` (no saved card) or `payment_declined`
- `403`: Valid key but missing required permission
- `429`: Rate limit or daily quota exceeded
- `500`: `payment_setup_failed` (nothing was charged) or `internal_error`
- `503`: `quote_unavailable`: no registrar price right now. Retry shortly.

---

[API](https://skmtc.dev/namemy/apis/namemy-app-api.md) · [All operations](https://skmtc.dev/namemy/apis/namemy-app-api/llms.txt) · [OpenAPI document](https://skmtc.dev/namemy/apis/namemy-app-api/revisions/1c302ede4b63?raw)