Skip to content
Extrovert Extrovert Docs

Request a plan change for human approval

POST
/v1/commerce/requests/plan-changes

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “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

Section titled “Request Body required ”
object
target_plan
required
string
Allowed values: free developer startup
project_id

Required on the console creation route; agent routes derive it from the key.

string
rationale
string
<= 2000 characters

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Request recorded

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

Section titled “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

401

Section titled “401 ”

Missing or invalid credential.

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

Section titled “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