Buy a Domain

# Pre-purchase
GET    /v1/domain-purchases/check?hostname=…

# Buy
POST   /v1/domain-purchases                            (optionally autoConnect)
GET    /v1/domain-purchases                            (filterable list)
GET    /v1/domain-purchases/:id
PATCH  /v1/domain-purchases/:id                        (toggle autoRenew / cancel)

# Live state at the registrar
GET    /v1/domain-purchases/:id/details

# Connect to your edge
POST   /v1/domain-purchases/:id/connect

# DNS
GET    /v1/domain-purchases/:id/dns
PUT    /v1/domain-purchases/:id/dns

# Nameservers
PUT    /v1/domain-purchases/:id/nameservers

# Renewal
POST   /v1/domain-purchases/:id/renew

# Transfer out
GET    /v1/domain-purchases/:id/auth-code

The Buy-a-Domain API lets your users register custom domains without leaving your app. You call us, we charge your card, we register the hostname at the upstream registrar with the contact info you supply, and we hand you back a purchase record.

Who pays whom

your end-user → you → Domainee → registrar

You mark up however you want and bill your end-user out of band. Domainee charges your workspace's saved Stripe card off-session as soon as the purchase API call lands — no payment link, no checkout page, no user interaction. Same mechanism that handles your monthly Domainee subscription.

If the registrar rejects the registration after we've taken your money, we refund the charge automatically and mark the purchase row as refunded.

Pricing

what you pay Domainee  =  registrar's wholesale price  +  $1 flat

Wholesale prices come from the registrar in real time. The $1 is Domainee's per-purchase operational fee (refund risk, FX, support). What you charge your end-user is entirely up to you.

You can preview the exact price before committing:

curl "https://api.domainee.dev/v1/domain-purchases/check?hostname=acme.com" \
  -H "Authorization: Bearer $DOMAINEE_API_KEY"

Returns the live wholesaleCents + feeCents + totalCents. See Check availability + price.

What gets stored

Each purchase writes a row to your workspace's domain_purchases ledger. You can list and filter that ledger any time — by hostname, by status, by date range, or by the opaque customerReference string you stashed at buy time. See List purchases.

What gets registered

The hostname is registered at the upstream registrar with the registrant contact you supplied — the end-user is the legal owner of record, not you and not Domainee. WHOIS privacy is enabled by default (free).

The domain registration itself is just the legal record. To actually serve content on it you have two paths:

Option 1 — autoConnect (one API call total). Pass autoConnect: { originUrl } on the POST and we do the buy AND the edge provisioning AND set the DNS in one shot. Recommended for most flows.

Option 2 — Connect later. Skip autoConnect, then later call POST /:id/connect to provision on the edge + set DNS. Useful when the user buys first and decides where to point the domain later.

What you can do after the purchase

Acme can build a full domain management dashboard for their end-user using these endpoints — no Namecheap login required on anyone's side:

• Get live details — expiry, nameservers, lock state
• List and set DNS records — A, CNAME, MX, TXT, etc.
• Set custom nameservers — switch to Cloudflare / Vercel / Route 53
• Renew the registration
• Cancel (turn off auto-renew)
• Get the auth code for a transfer-out

Webhooks

Four events fire across the purchase lifecycle:

• domain_purchase.completed — registrar confirmed registration
• domain_purchase.failed — charge failed, or registrar refused; refund applied where needed
• domain_purchase.renewed — auto-renew or manual renewal succeeded
• domain_purchase.renewal_failed — renewal attempt failed; domain may expire if not resolved

Same signed delivery + retry behavior as the rest of Domainee.