Sign in
Domains

Create Domain

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.

post/domains

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

account_idstring

Account ID, prefixed biz_. Required for user credentials; otherwise defaults to the credential's account.

app_idstring required

App ID, prefixed app_. The app must belong to the account.

domainstring required

Bare hostname, such as example.com or checkout.example.com. Wildcards, paths, schemes, and ports are not accepted.

metadataobject

Custom string keys and values.

replace_existingboolean

Explicitly transfer a domain from its current owner after publishing this new claim's TXT proof. Create the claim after the current owner verified.

Example request

{
  "app_id": "app_xxxxxxxxxxxxxx",
  "domain": "store.example.com",
  "metadata": {
    "project": "website"
  }
}

Response

Domain claim created

account_idstring required

ID of the account claiming or owning this domain, prefixed biz_.

app_idstring required

ID of the app assigned to this domain, prefixed app_.

certificate_statusstring nullable required

Cloudflare's latest certificate issuance status.

created_atstring required

When the domain claim was created, as an ISO 8601 timestamp.

dns_status'pending' | 'valid' | 'invalid' | 'unknown' required

Result of the most recent DNS routing check. Ownership is verified separately.

domainstring required

Normalized hostname, such as checkout.example.com.

hostname_statusstring nullable required

Cloudflare's latest hostname activation status.

idstring required

Domain ID, prefixed dom_.

last_checked_atstring nullable required

When DNS and provider state were last checked, as an ISO 8601 timestamp.

metadataobject 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_atstring required

When the domain was last updated, as an ISO 8601 timestamp.

verification_expires_atstring nullable required

When an unverified claim is automatically deleted, 48 hours after creation, as an ISO 8601 timestamp.

verified_atstring nullable required

When Whop verified the ownership TXT record, as an ISO 8601 timestamp.

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "app_id": "app_xxxxxxxxxxxxxx",
  "created_at": "2026-01-01T12:00:00.000Z",
  "dns_records": [
    {
      "name": "_whop.shop.example.com",
      "type": "TXT",
      "value": "whop-domain-verification=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
  ],
  "dns_status": "pending",
  "domain": "shop.example.com",
  "id": "dom_xxxxxxxxxxxxxx",
  "issues": [
    {
      "code": "dns_required",
      "message": "Point DNS to Whop using the routing records. Disable other CDN proxies while connecting."
    }
  ],
  "metadata": {},
  "status": "deleting",
  "updated_at": "2026-01-01T12:00:00.000Z",
  "verification_expires_at": "2026-01-01T12:00:00.000Z"
}

Changes

Changed in 1 of the 74 revisions of this API.1

Of the 74 revisions, 1 has no diff computed.