/v1/admin/package-commerce

GET /v1/admin/package-commerce/orders

List all package orders for one explicit tenant

operationId

listTenantPackageOrdersAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/package-commerce/orders/{order_id}

Get one order in an explicit tenant scope

operationId

getTenantPackageOrderAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/package-commerce/orders/{order_id}/events

List sanitized events for one tenant order

operationId

listTenantPackageOrderEventsAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/package-commerce/orders/{order_id}/refund

Apply an approved partial or cumulative refund

operationId

refundPackageOrder

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Description (from the contract)

Requires a platform principal with billing.adjustments.manage and an explicit tenant_id. The core requires a matching unexpired, unused two-person approval fact; this endpoint neither creates nor weakens that approval. gross_amount_minor is the gross amount for this refund action.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/package-commerce/orders/{order_id}/void

Void an eligible order using a one-time approval fact

operationId

voidPackageOrder

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Description (from the contract)

Requires billing.adjustments.manage and an explicit tenant_id. The approval must match the order, tenant, operation, executor, and validity window. Existing refunds or a consumed approval remain hard failures.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/package-commerce/sold

List sold packages across tenants

operationId

listAdminSoldPackages

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Description (from the contract)

Requires a platform-scope principal. Empty optional parameters must be omitted; duplicate and unknown parameters are rejected. Product options include all sold products independent of filters, without a 100-item cap. Names come from the effective immutable product snapshot. User display IDs come from users.display_id. A subscription ID is its actual UUID, never its revision. Expiry week is the next 7 days; month is the next calendar month, both excluding already expired records. Expired includes ends_at equal to the query time. Status is the stored lifecycle status; an expired active subscription still has lifecycle_status active. Usage is currently null because the commerce read model has no authoritative settled per-cycle counter; unknown usage matches neither exhausted nor remaining. A traffic limit of -1 means unlimited. CNAME searches current and last-known-good hostname claims associated with the subscription or one of its sites. Search values are literal case-insensitive substrings, not SQL patterns.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/package-commerce/sold/commands

operationId

administerSoldPackages

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：package_subscriptions.manage

Description (from the contract)

Executes all selected items in one transaction. The live session and RBAC are rechecked, including replay. A changed body under an existing key is rejected. Editing appends an entitlement snapshot without rewriting the purchased catalog version or historical prices. Enable/disable is independent of cancellation. Safe deletion rejects live resources; cascade deletion uses audited resource deletion and edge publication. Neither mode refunds money; unsettled orders, held balances and scheduled entitlements block deletion. Sync copies only selected fields to bound websites and L4 forwarding resources, then persists signed edge publication, rollout and node command outbox. Publication receipts are polled separately and command success does not imply every node has applied it.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

GET /v1/admin/package-commerce/sold/{subscription_id}

operationId

getAdminSoldPackage

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Parameters

Responses

What to do on failure

• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.

↑ Back to list

GET /v1/admin/package-commerce/sold/{subscription_id}/sync

operationId

getAdminSoldPackageSync

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Parameters

Responses

What to do on failure

• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.

↑ Back to list

GET /v1/admin/package-commerce/subscriptions

List effective sold subscriptions for one explicit tenant

operationId

listSoldPackageSubscriptionsAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Description (from the contract)

Uses the fixed-time effective entitlement projection. Each subsequent page reuses all three values from the endpoint- and tenant-bound signed cursor, so later entitlement backfills, renewals, or cancellations cannot create mixed facts.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/package-commerce/subscriptions

Open a package subscription for an active tenant member without an order

operationId

openPackageSubscriptionAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：package_subscriptions.manage

Description (from the contract)

Creates the subscription, immutable revision-one state, and active manual_open entitlement atomically. It never fabricates an order, payment, or fulfillment. Unknown outcomes may be retried only with the exact original body and Idempotency-Key.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list

POST /v1/admin/package-commerce/subscriptions/{subscription_id}/cancel

Cancel a tenant subscription as administrator

operationId

cancelPackageSubscriptionAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：package_subscriptions.manage

Description (from the contract)

Physical deletion is not supported by cancellation. Use sold package commands for independent enable/disable and audited deletion.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.
• 412 The revision changed: read the latest ETag, decide again, then send the new If-Match.

↑ Back to list

POST /v1/admin/package-commerce/subscriptions/{subscription_id}/suspend

Suspend one package subscription as an administrator

operationId

suspendPackageSubscriptionAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：package_subscriptions.manage

Description (from the contract)

Stops publishing the subscription's sites and forwards (configuration kept) and republishes the scope at once. The term keeps running. Only this subscription is affected. Suspending an already suspended subscription succeeds without a change. reason is required.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

POST /v1/admin/package-commerce/subscriptions/{subscription_id}/unsuspend

Unsuspend one package subscription as an administrator

operationId

unsuspendPackageSubscriptionAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：package_subscriptions.manage

Description (from the contract)

Publishes the subscription's sites and forwards again at once. Unsuspending a subscription that is not suspended succeeds without a change.

Parameters

Request body

application/json · Required：Yes

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.

↑ Back to list

GET /v1/admin/package-commerce/traffic-purchases/{order_id}

Get one sanitized traffic-purchase result for an explicit tenant

operationId

getTenantTrafficPackagePurchaseAsPlatform

Auth

• Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.

Required permissions

All of：billing.adjustments.manage

Description (from the contract)

The platform principal must name the target tenant. A purchase outside that tenant scope is indistinguishable from an unknown order.

Parameters

Responses

What to do on failure

• 400 Fix the parameters or body per the field list; do not retry unchanged.
• 401 Check the credential format and whether it expired or was rotated.
• 403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.
• 404 The resource does not exist or belongs to another tenant.
• 503 A dependency is unavailable: retry later with the original Idempotency-Key.

↑ Back to list