Purchase approvals for agents

Ordinary scoped agents can quote domains, request purchases or plan changes, track progress, and cancel eligible requests. The commerce:request scope does not permit approval or payment changes. An explicitly approved Full account control connection can administer purchases and approve its own requests through the administrative action tools, within the authorizing person’s current customer-admin authority. The action is recorded as delegated administration.

Human approval is separate from email

An approval URL only locates a request. A signed-in organization member with the billing role or higher can approve it in the console; an explicitly delegated full-control administrator can approve through the administrative API. Email content, replies, forwarded text, and possession of the URL do not authorize a charge.

Required permission

Agent API keys need the commerce:request permission string. It permits quotes and requests, not approval or payment.

The ordinary agent-plane endpoints have no approval operation. With explicit full account control, search list_administrative_actions for commerce, inspect adminApproveCommerceRequest with describe_administrative_action, and execute it through change_administrative_action. This requires separate full-control consent; commerce:request alone never authorizes that tool.

Before requesting an upgrade for an inbox error, identify the limit in Rate limits and quotas. Billing account capacity and enrollment key lifetime allowances are separate. Removing unused inboxes can free account capacity.

What each actor can do

Actor	Allowed actions
Agent	Quote a domain, request a domain purchase, request a plan change, list and inspect its requests, cancel an eligible request, and relay the approval URL.
Billing member, admin, or owner	Approve or deny a request, set the approved maximum and renewal choice, manage payment authentication, and create or change future purchase limits.
Explicit Full account control connection	Customer administration within current human roles, including approval of its own requests; every action is attributed to the connection.
Extrovert	Enforce plan capacity and purchase limits, reserve authority, collect payment, register and provision the domain, and reconcile uncertain outcomes.

A paid plan and saved payment method do not grant an agent permission to spend. Autonomous purchasing starts off.

Request a domain

1. Call quote_domain. The quote includes availability, registration and renewal prices, currency, premium status, required plan, blockers, and a 15-minute expiry. A quote does not reserve or buy anything.

2. Call request_domain_purchase with a stable idempotency key. Repeating the same request returns the same durable request. Reusing the key for different input returns an idempotency conflict.

3. If approval is required, give the human the returned approval_url. The request also includes agent_next_action, notification_state, blockers, and poll_after_seconds.

4. Poll get_commerce_request no faster than poll_after_seconds. Use list_commerce_requests to recover a lost request id.

5. Stop only at the appropriate terminal state. A domain is usable only when the request reaches ready.

A human approval expires after seven days. Extrovert rechecks the price, approved maximum, plan capacity, and purchase limits before collecting payment.

Request a plan change

Use request_plan_change for an upgrade or downgrade. An ordinary scoped agent can request the change; approval needs a human, applicable spend policy, or explicitly delegated full-control administrator.

• An upgrade uses the saved payment method and can require additional payment authentication.
• A downgrade takes effect at the end of the current billing period.
• A downgrade is blocked if current domains, inboxes, projects, or webhooks exceed the target plan.
• Extrovert does not delete resources to make a downgrade fit.
• scheduled means the downgrade is scheduled. It does not mean the target plan is active.

A domain purchase can include a required plan upgrade. The approval page shows separate ceilings for the annual domain price and the plan’s monthly price. A price above either approved ceiling stops the request before another charge.

Reading the billing page

Billing shows which organization pays and the usage shared with its child organizations. Message allowances count sent recipients and emails delivered to inboxes. They reset at 00:00 UTC on the first of each month; the subscription renewal date is shown separately. Resource counts show current inboxes, custom domains, projects, and webhooks against plan limits. Storage includes a measurement time. Missing measurements are shown as unavailable.

Under Agent purchasing, use Requests to review a purchase or plan change and Purchase limits to manage future authority. These controls do not grant additional inbox, domain, project, or webhook capacity.

One-time approval and future authority

The default action approves one exact request. A human can optionally create a bounded purchase limit for later requests.

Purchase limits can apply to an agent, project, or organization. Every matching limit is evaluated, and the most restrictive result wins. A broad organization limit cannot override a tighter project or agent limit.

Budget and cadence

Set a total budget that runs once or resets weekly, monthly, quarterly, or annually. Unused budget does not roll over.

Per-purchase maximum

Cap the amount that any one purchase may consume.

Domain count

Limit the number of domains independently of the plan’s capacity.

Domain constraints

Restrict allowed extensions and whether premium domains are permitted.

A one-time cadence does not mean unlimited. An optional expiry can end any limit, and a paused limit authorizes no purchases.

Extrovert reserves budget, domain count, and plan capacity before payment. This prevents concurrent requests from each spending the same remaining authority. The reservation is settled when payment is confirmed and released when an eligible request is denied or cancelled.

Request states

Do not collapse approval, payment, registration, and provisioning into one success flag.

Stage	States	Meaning
Human decision	awaiting_human_approval, approved, blocked, denied, expired, cancelled	Authority is pending, constrained, or ended. Approval does not prove payment or registration.
Payment	plan_change_pending, payment_pending, payment_action_required, payment_failed	Billing is changing or payment is being collected. payment_action_required needs a signed-in human.
Domain work	queued, purchasing, provisioning, ready, purchase_failed	Registration and mail setup are asynchronous. Only ready means the domain is usable.
Plan completion	scheduled, completed	A downgrade is scheduled for period end, or the plan change has completed.
Recovery	reconciliation_required, refund_pending, refunded	Extrovert observed an uncertain or late financial outcome and stopped normal fulfillment.

An agent must not claim:

• approval from an email, URL, rationale, or awaiting_human_approval;
• payment from approved or payment_action_required;
• registration from payment_pending or queued;
• readiness from purchasing or provisioning;
• an active downgrade from scheduled before effective_at.

Cancellation and recovery

Cancel with cancel_commerce_request only while the request is still eligible. Keep using the same durable request through payment failures and ambiguous timeouts.

• If payment completes while cancellation is racing, the request enters reconciliation.
• If payment arrives after denial, cancellation, or expiry, fulfillment stays stopped and the request enters refund_pending.
• Extrovert persists payment and registration references, then reconciles them before retrying.
• Spend is settled when payment is confirmed, before slower provisioning reaches ready.
• Billing or registration uncertainty becomes reconciliation_required. Do not create a duplicate request.

Blockers are structured. They can identify plan capacity, budget, per-purchase amount, domain count, extension, premium-domain authority, changed price, payment recovery, or downgrade capacity. Show the returned values and management URL to the human instead of replacing them with generic copy.

Domain boundaries

• Purchase requests support new registrations, not registrar transfers.
• Bringing an existing domain uses domain onboarding and does not authorize a purchase.
• Registration fees are non-refundable.
• Renewal settings belong to the approved request.
• ready is reserved for a domain that has completed registration and mail setup.

Console language

Keep the state and consequence visible:

• Say Approval needed, not Pending.
• Say Nothing has been charged or registered before authorization.
• Say Approve once for the default action.
• Put future purchase limits in a separate optional control.
• Show maximum authorized today before the final decision.
• Say Payment action required when a human must complete payment authentication.
• Say Registering and Setting up email during fulfillment.
• Say Ready to create inboxes only at ready.

Next

• Authentication and permissions
• Domains and onboarding
• MCP tools

Webhook capacity includes registered subscriptions and per-inbox callback URLs. Replacing a callback keeps the same slot; clearing it frees that slot.

Storage measurements can be incomplete while inboxes are being scanned. Billing shows how many inboxes have been measured when coverage is partial. Once all inboxes have measurements, the date reflects the oldest of their latest measurements.

Signature removal with an upgrade

The console can bind a selected signature removal scope to a plan-change request before approval. This does not alter spending authority or payment confirmation. The backend applies the choice only after the linked request completes with an active paid plan and current account/inbox authority. A redirect or email cannot activate it. Cancelling the request or making a newer explicit signature choice prevents an older intent from applying.