Create an exact-price domain request without charging or registering

POST

/v1/admin/orgs/{org_id}/commerce/requests/domain-purchases

• Production
• Local

Authorizations

• ClerkSession
• AgentKey
  account:admin

Parameters

Path Parameters

org_id

required

string

Header Parameters

Idempotency-Key

string

Optional client-supplied key making a CREATE exactly-once. A retry with the same key returns the ORIGINAL response (same status + body) instead of creating a duplicate; the same key with a different request body returns 409. The body field client_id is honored as an alias when this header is absent. The key is scoped per tenant (and per agent on the agent plane), so keys never collide across callers.

Request Body ^required

object

domain

required

string

scope

string

default: project

Allowed values: project

project_id

string

rationale

string

<= 2000 characters

auto_renew

boolean

default: true

Responses

201

Review request created

object

object

required

string

Allowed values: commerce_request

id

required

string

project_id

string

agent_id

Present when an agent initiated the request.

string

kind

required

string

Allowed values: domain_purchase plan_change

state

required

string

domain

string

domain_scope

string

Allowed values: org project

target_plan

string

current_plan

string

rationale

string

currency

required

string

quote_cents

required

integer format: int64

renewal_cents

required

integer format: int64

approved_max_cents

integer format: int64

quote_expires_at

string format: date-time

auto_renew

required

boolean

required_plan

string

required_plan_price_cents

integer format: int64

blocker_code

string

blockers

required

Array<object>

object

code

required

string

message

required

string

scope

string

limit_id

string

used_cents

integer format: int64

reserved_cents

integer format: int64

limit_cents

integer format: int64

requested_cents

integer format: int64

used_count

integer format: int64

reserved_count

integer format: int64

limit_count

integer format: int64

reset_at

string format: date-time

manage_url

string format: uri

approval_url

string format: uri

payment_action_url

string format: uri

external_job_id

string

effective_at

string format: date-time

agent_next_action

required

string

retry_safe

required

boolean

poll_after_seconds

required

integer

version

required

integer format: int64

notification_state

string

notification_last_error

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

400

Invalid request.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

403

Authenticated but lacking the required scope, or out of quota.

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean

409

Resource conflict (e.g. a duplicate entry).

The canonical error envelope. error is a stable machine code.

object

error

required

Stable error code (e.g. unauthorized, forbidden, not_found, invalid, quota_exceeded, rate_limited).

string

Example

forbidden

message

Human-readable detail (never leaks internals).

string

Example

missing required scope

reason

Machine-readable quota reason. inbox_limit_exceeded means billing account inbox capacity across all organizations and projects sharing that account; enrollment_token_mailbox_budget_exhausted means the enrollment key lifetime creation allowance. Read message for recovery; inbox counts are separate from sending quotas.

string

used

Consumed plus reserved units.

integer format: int64

delta

Requested additional units.

integer format: int64

limit

integer format: int64

remaining

integer format: int64

consumed

integer format: int64

reserved

integer format: int64

next_reset_at

Next UTC usage-period boundary; pending reservations survive this boundary.

string format: date-time

upgrade_required

boolean