---
title: "Create Domain"
method: POST
path: "/domains"
tags: ["Domains"]
---

# Create Domain

`POST /domains`

Creates an unverified claim and returns DNS instructions. A claim does not reserve the hostname globally. Publish its unique TXT record; ownership verification, DNS checks, and certificate provisioning run automatically. Unverified claims are deleted after 48 hours.

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `account_id` string — Account ID, prefixed biz_. Required for user credentials; otherwise defaults to the credential's account.
  - `app_id` string, required — App ID, prefixed app_. The app must belong to the account.
  - `domain` string, required — Bare hostname, such as example.com or checkout.example.com. Wildcards, paths, schemes, and ports are not accepted.
  - `metadata` object — Custom string keys and values.
  - `replace_existing` boolean — Explicitly transfer a domain from its current owner after publishing this new claim's TXT proof. Create the claim after the current owner verified.

## Response `201`

Domain claim created

- Domain
  - `account_id` string, required — ID of the account claiming or owning this domain, prefixed `biz_`.
  - `app_id` string, required — ID of the app assigned to this domain, prefixed `app_`.
  - `certificate_status` string, nullable, required — Cloudflare's latest certificate issuance status.
  - `created_at` string, required — When the domain claim was created, as an ISO 8601 timestamp.
  - `dns_records` DomainDnsRecord[], required
    - `name` string, required — Full hostname where the record must be published.
    - `type` 'TXT' | 'CNAME' | 'A' | 'AAAA', required — DNS record type.
    - `value` string, required — DNS record content.
  - `dns_status` 'pending' | 'valid' | 'invalid' | 'unknown', required — Result of the most recent DNS routing check. Ownership is verified separately.
  - `domain` string, required — Normalized hostname, such as checkout.example.com.
  - `hostname_status` string, nullable, required — Cloudflare's latest hostname activation status.
  - `id` string, required — Domain ID, prefixed `dom_`.
  - `issues` DomainIssue[], required
    - `code` string, required — The source of the setup issue.
    - `message` string, required — What needs attention before the domain can serve the website.
  - `last_checked_at` string, nullable, required — When DNS and provider state were last checked, as an ISO 8601 timestamp.
  - `metadata` object, required — Custom string keys and values attached to this domain.
  - `status` 'pending_verification' | 'provisioning' | 'active' | 'action_required' | 'deleting' | 'removed', required — Domain lifecycle. Only active domains resolve to their app.
  - `updated_at` string, required — When the domain was last updated, as an ISO 8601 timestamp.
  - `verification_expires_at` string, nullable, required — When an unverified claim is automatically deleted, 48 hours after creation, as an ISO 8601 timestamp.
  - `verified_at` string, nullable, required — When Whop verified the ownership TXT record, as an ISO 8601 timestamp.

## Other responses

- `409` — Conflict

## Changes

> 61 revisions in range; 1 not diffed.

- **2026-09-10** `2a25564a92d5` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/whop/apis/whop-api/changes/domains/post.md)

---

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