Operation details
GET /v1/package-commerce/catalog
List package products purchasable by the authenticated tenant user
- operationId
listPublishedPackageOffers- 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.read
Description (from the contract)
Requires package_subscriptions.read. Only enabled products linked to a currently visible package group are returned. The first page freezes the authenticated tenant/user scope, business-time snapshot, catalog publish watermark, and package-group visibility watermark; later pages reuse the endpoint- and principal-bound signed cursor so catalog changes cannot produce mixed pages. Purchasing a returned offer separately requires package_subscriptions.manage.
Parameters
listPublishedPackageOffers Parameters| Name | In | Type | Required | Description |
|---|
kind | query | string | Yes | Public catalog projection kind. This endpoint currently exposes package products only. |
|---|
group_id | query | string(uuid) | No | BILL-13: only products in this visible package group (an ID from the first page's groups). Bound to the signed cursor; a cursor minted for another group, or for no group, is refused with 400. |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope bound to endpoint, target tenant, and owner user where applicable. Tampering or cross-scope reuse returns package_commerce_validation_error. |
|---|
Responses
listPublishedPackageOffers Responses| Status | Description |
|---|
200 | Stable public package catalog page and current caller eligibility. Fields：items: array<PackageCatalogItem> next_cursor?: string eligibility: CatalogEligibility groups?: array<PackageCatalogGroup> |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/orders
List the authenticated tenant user's package orders
- operationId
listMyPackageOrders- 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.read
Description (from the contract)
Requires package_subscriptions.read. Results are constrained by both principal scope and principal user ID. tenant_id is rejected.
Parameters
listMyPackageOrders Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope bound to endpoint, target tenant, and owner user where applicable. Tampering or cross-scope reuse returns package_commerce_validation_error. |
|---|
product_kind | query | string: package_subscription / traffic_package | No | Optional order product filter shared by tenant and platform order reads. |
|---|
state | query | string: created / paid / fulfilled / cancelled / refund_applied / void_applied / failed | No | Optional latest order state filter shared by tenant and platform order reads. |
|---|
request_id | query | string | No | Optional X-Request-ID the order was created with, so a buyer can confirm the outcome of the original command. |
|---|
Responses
listMyPackageOrders Responses| Status | Description |
|---|
200 | Stable keyset page ordered by created_at and order UUID descending. Fields：items: array<Order> next_cursor?: string |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/orders/{order_id}
Get one visible package order
- operationId
getMyPackageOrder- 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.read
Description (from the contract)
A foreign-tenant or different-owner order returns the same 404 as an unknown order and does not disclose existence.
Parameters
getMyPackageOrder Parameters| Name | In | Type | Required | Description |
|---|
order_id | path | string(uuid) | Yes | — |
|---|
Responses
getMyPackageOrder Responses| Status | Description |
|---|
200 | Sanitized visible order. Fields：id: string(uuid) display_id: string tenant_scope_id: string(uuid) user_id: string(uuid) user_display_id: string operation: string: purchase / renew / upgrade / downgrade / traffic_package_purchase subscription_id?: string(uuid) product_kind: string: package_subscription / traffic_package product_id: string(uuid) product_revision: integer(int64) protection?: object traffic_product_snapshot_id?: string(uuid) package_period?: string: month / quarter / year currency: string original_amount_minor: integer(int64) discount_amount_minor: integer(int64) payable_amount_minor: integer(int64) settlement_direction: string: debit / credit / hold funding_source: string: balance / provider / reseller effective_mode: string: immediate / next_cycle effective_at: string(date-time) state: string: created / paid / fulfilled / cancelled / refund_applied / void_applied / failed revision: integer(int64) created_at: string(date-time) seller_scope_id?: object wholesale_minor?: integer(int64) product_name?: string |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/orders/{order_id}/events
List sanitized order state events in revision order
- operationId
listMyPackageOrderEvents- 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.read
Description (from the contract)
Event payload, actor, request/trace IDs, approval IDs, ledger IDs, holds, provider data, and digests are deliberately omitted.
Parameters
listMyPackageOrderEvents Parameters| Name | In | Type | Required | Description |
|---|
order_id | path | string(uuid) | Yes | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope bound to endpoint, target tenant, and owner user where applicable. Tampering or cross-scope reuse returns package_commerce_validation_error. |
|---|
Responses
listMyPackageOrderEvents Responses| Status | Description |
|---|
200 | Stable event page ordered by revision ascending. Fields：items: array<OrderEvent> next_cursor?: string |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/provider-callbacks/{provider}
Authenticate and apply one raw payment-provider callback
- operationId
applyVerifiedPaymentProviderCallback- Auth
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
No bearer identity is accepted as proof. All four callback headers must each have exactly one non-empty value without surrounding whitespace. The timestamp is canonical Unix seconds within the configured freshness window. The HMAC-SHA256 input is eleven newline-separated values in this order: cdnca.package-commerce.provider-callback.v1, the provider path value, provider_account_id, key ID, timestamp, external_event_id, external_payment_id, event_kind, canonical decimal amount_minor, currency, and the lowercase hexadecimal SHA-256 of the exact raw body. X-CDNCA-Callback-Signature is v1= followed by the canonical base64url-no-padding encoding of the 32-byte HMAC. Verification binds the provider, account, and key before the normalized callback reaches the commerce core. Exact and concurrent signed retries pass authentication; durable external_event_id plus raw payload SHA-256 idempotency returns the committed replay, while a changed payload returns provider_event_conflict. Raw payloads, credentials, keyring contents, and secrets are never returned by this endpoint.
Parameters
applyVerifiedPaymentProviderCallback Parameters| Name | In | Type | Required | Description |
|---|
provider | path | string | Yes | — |
|---|
X-CDNCA-Callback-Version | header | string | Yes | Exactly one value selecting callback signature version 1. |
|---|
X-CDNCA-Callback-Key-ID | header | string | Yes | Exactly one configured key identifier bound to the provider and provider account. |
|---|
X-CDNCA-Callback-Timestamp | header | string | Yes | Exactly one canonical base-10 Unix-seconds value that fits signed int64. |
|---|
X-CDNCA-Callback-Signature | header | string | Yes | Exactly one v1= prefixed canonical base64url-no-padding encoding of the 32-byte HMAC-SHA256. |
|---|
X-Request-ID | header | string | No | — |
|---|
traceparent | header | string | No | — |
|---|
Request body
application/json · Required：Yes
applyVerifiedPaymentProviderCallback Request body| Name | Type | Required | Description |
|---|
version | integer | Yes | — |
|---|
provider_account_id | string | Yes | — |
|---|
external_event_id | string | Yes | — |
|---|
external_payment_id | string | Yes | — |
|---|
event_kind | string: payment_succeeded / payment_failed / refund_succeeded / void_succeeded | Yes | — |
|---|
amount_minor | integer(int64) | Yes | — |
|---|
currency | string | Yes | — |
|---|
occurred_at | string(date-time) | Yes | — |
|---|
Responses
applyVerifiedPaymentProviderCallback Responses| Status | Description |
|---|
200 | Normalized provider event processed or replayed. Fields：processing_result: string: applied / rejected_signature / rejected_mismatch / ignored_terminal / ignored_out_of_order / failed_fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication failed because a required single-value callback header, provider/account/key binding, freshness check, canonical HMAC signature, application/json content type, strict UTF-8 JSON body, or 256 KiB body bound was invalid. The commerce core was not invoked, and the response does not reveal whether a provider, account, or key exists. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Callback verification is unavailable before the commerce core is invoked (payment_callback_provider_unavailable), or the write outcome is unknown after a verified callback reaches the core (package_commerce_result_unknown). The stable error code distinguishes whether an unchanged signed request may be retried. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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/package-commerce/purchases
Purchase a package subscription for the authenticated tenant user
- operationId
purchasePackageSubscription- 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)
Requires a tenant principal with package_subscriptions.manage. Tenant and buyer IDs are derived from the live principal and cannot be supplied in the request body. Unknown results may be retried only with the original Idempotency-Key, If-Match value where applicable, and identical payload.
Parameters
purchasePackageSubscription Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
purchasePackageSubscription Request body| Name | Type | Required | Description |
|---|
product_id | string(uuid) | Yes | — |
|---|
product_revision | integer(int64) | Yes | — |
|---|
period | string: month / quarter / year | Yes | — |
|---|
site_limit | integer(int64) | Yes | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
node_limit | integer(int64) | Yes | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
timezone | string | Yes | — |
|---|
cycle_policy | object | object | Yes | — |
|---|
traffic_factor | TrafficFactor | Yes | — |
|---|
promotion | PromotionReference | No | — |
|---|
payment | BalancePayment | ProviderPayment | Yes | — |
|---|
Responses
purchasePackageSubscription Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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/package-commerce/reseller/customers/{customer_scope_id}/orders
A reseller lists one of its customers' package orders
- operationId
resellerListCustomerOrders- 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：reseller.customers.read
Description (from the contract)
Reseller tenant session with reseller.customers.read or reseller.customers.manage; the customer must be under the caller's active reseller scope (otherwise 403). Lists the whole customer scope (every owner); wholesale_minor is the reseller's own cost and is returned. tenant_id and operation are rejected.
Parameters
resellerListCustomerOrders Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope bound to endpoint, target tenant, and owner user where applicable. Tampering or cross-scope reuse returns package_commerce_validation_error. |
|---|
product_kind | query | string: package_subscription / traffic_package | No | Optional order product filter shared by tenant and platform order reads. |
|---|
state | query | string: created / paid / fulfilled / cancelled / refund_applied / void_applied / failed | No | Optional latest order state filter shared by tenant and platform order reads. |
|---|
request_id | query | string | No | Optional X-Request-ID the order was created with, so a buyer can confirm the outcome of the original command. |
|---|
Responses
resellerListCustomerOrders Responses| Status | Description |
|---|
200 | Stable keyset page ordered by created_at and order UUID descending. Fields：items: array<Order> next_cursor?: string |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/reseller/customers/{customer_scope_id}/purchases
A reseller buys one of its packages for its own customer
- operationId
resellerPurchaseForCustomer- 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：reseller.customers.manage
Description (from the contract)
The caller is a reseller tenant session with reseller.customers.manage; the customer must be under it and the package must be the reseller's. Only the reseller's prepaid wholesale cost (W, from its price list) is charged; the customer's balance is untouched (funding_source reseller). The subscription belongs to owner_user_id in the customer scope. 422 reseller_prepaid_insufficient when the prepaid balance is short of W (nothing is written); 422 reseller_wholesale_unpriced when the main line group has no wholesale price for the period.
Parameters
resellerPurchaseForCustomer Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
resellerPurchaseForCustomer Request body| Name | Type | Required | Description |
|---|
owner_user_id | string(uuid) | Yes | — |
|---|
product_id | string(uuid) | Yes | — |
|---|
product_revision | integer(int64) | Yes | — |
|---|
period | string: month / quarter / year | Yes | — |
|---|
Responses
resellerPurchaseForCustomer Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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/package-commerce/reseller/customers/{customer_scope_id}/subscriptions
A reseller lists one of its customers' package subscriptions
- operationId
resellerListCustomerSubscriptions- 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：reseller.customers.read
Description (from the contract)
Same snapshot and paging rules as /v1/package-commerce/subscriptions, over the whole customer scope; reseller.customers.read or reseller.customers.manage, customer under the caller (otherwise 403).
Parameters
resellerListCustomerSubscriptions Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope bound to endpoint, target tenant, and owner user where applicable. Tampering or cross-scope reuse returns package_commerce_validation_error. |
|---|
status | query | string: active / expired / cancelled | No | Effective status at the frozen snapshot. active ends after snapshot_at; expired ends at or before snapshot_at; cancelled always follows the immutable cancelled lifecycle fact regardless of end_at. |
|---|
end_at_from | query | string(date-time) | No | Inclusive canonical UTC microsecond lower bound for end_at. |
|---|
end_at_to | query | string(date-time) | No | Exclusive canonical UTC microsecond upper bound for end_at. |
|---|
include_product_name | query | string: true / false | No | Accepts exactly one lowercase true or false. Empty, repeated, or other values return 400. Omitted or false preserves the legacy response shape. true includes product_name only when the selected effective entitlement's immutable product_snapshot.name is a JSON string, preserved without normalization. Missing, null, or non-string names are omitted. The current product catalog is never used. This projection does not change subscription membership, ordering, or the cursor's tenant, owner, time, and high-water bounds. |
|---|
page | query | integer | No | Page-jump mode (1-based, max 10000, mutually exclusive with cursor). |
|---|
Responses
resellerListCustomerSubscriptions Responses| Status | Description |
|---|
200 | Stable effective-subscription projection page. Fields：items: array<Subscription> next_cursor?: string total?: integer(int64) |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/cancel
A reseller cancels its customer's subscription
- operationId
resellerCancelCustomerSubscription- 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：reseller.customers.manage
Description (from the contract)
Same behavior as the platform's cancel (the sites stop, no refund or ledger entry). The customer must be under the caller's active reseller scope.
Parameters
resellerCancelCustomerSubscription Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
resellerCancelCustomerSubscription Responses| Status | Description |
|---|
201 | Cancelled subscription or exact idempotent replay. Fields：subscription: object intent?: object |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
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.412 The revision changed: read the latest ETag, decide again, then send the new If-Match.
↑ Back to list
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/downgrade
A reseller downgrades its customer's subscription to another of its packages
- operationId
resellerDowngradeForCustomer- 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：reseller.customers.manage
Description (from the contract)
Only between the reseller's own packages, immediately. The customer pays nothing; the reseller's prepaid balance moves by the wholesale difference prorated over the remaining part of the current cycle (old price rounded down, new price rounded up, as proration-utc-v1). An upgrade charges it (422 reseller_prepaid_insufficient when short: nothing is written); a downgrade returns it. The order's seller is the reseller and wholesale_minor is the difference. If-Match is the quoted current subscription revision.
Parameters
resellerDowngradeForCustomer Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
resellerDowngradeForCustomer Request body| Name | Type | Required | Description |
|---|
product_id | string(uuid) | Yes | — |
|---|
product_revision | integer | Yes | — |
|---|
period | string: month / quarter / year | Yes | — |
|---|
Responses
resellerDowngradeForCustomer Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/renew
A reseller renews its customer's subscription to one of its packages
- operationId
resellerRenewForCustomer- 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：reseller.customers.manage
Description (from the contract)
Same rules as the reseller purchase: only W is charged. If-Match is the quoted current subscription revision. A renewal carrying a platform add-on cannot be reseller-placed (409).
Parameters
resellerRenewForCustomer Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
resellerRenewForCustomer Request body| Name | Type | Required | Description |
|---|
period | string: month / quarter / year | Yes | — |
|---|
Responses
resellerRenewForCustomer Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/suspend
Suspend one package subscription as the customer's reseller
- operationId
resellerSuspendCustomerSubscription- 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：reseller.customers.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
resellerSuspendCustomerSubscription Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
resellerSuspendCustomerSubscription Request body| Name | Type | Required | Description |
|---|
reason | string | Yes | — |
|---|
Responses
resellerSuspendCustomerSubscription Responses| Status | Description |
|---|
200 | The subscription after the change (or unchanged when already in that state), or an exact idempotent replay. Fields：subscription: object |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
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/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/unsuspend
Unsuspend one package subscription as the customer's reseller
- operationId
resellerUnsuspendCustomerSubscription- 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：reseller.customers.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
resellerUnsuspendCustomerSubscription Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
Responses
resellerUnsuspendCustomerSubscription Responses| Status | Description |
|---|
200 | The subscription after the change (or unchanged when already in that state), or an exact idempotent replay. Fields：subscription: object |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
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/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/upgrade
A reseller upgrades its customer's subscription to another of its packages
- operationId
resellerUpgradeForCustomer- 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：reseller.customers.manage
Description (from the contract)
Only between the reseller's own packages, immediately. The customer pays nothing; the reseller's prepaid balance moves by the wholesale difference prorated over the remaining part of the current cycle (old price rounded down, new price rounded up, as proration-utc-v1). An upgrade charges it (422 reseller_prepaid_insufficient when short: nothing is written); a downgrade returns it. The order's seller is the reseller and wholesale_minor is the difference. If-Match is the quoted current subscription revision.
Parameters
resellerUpgradeForCustomer Parameters| Name | In | Type | Required | Description |
|---|
customer_scope_id | path | string(uuid) | Yes | — |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
resellerUpgradeForCustomer Request body| Name | Type | Required | Description |
|---|
product_id | string(uuid) | Yes | — |
|---|
product_revision | integer | Yes | — |
|---|
period | string: month / quarter / year | Yes | — |
|---|
Responses
resellerUpgradeForCustomer Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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/package-commerce/subscriptions
List effective sold-subscription projections owned by the current user
- operationId
listMySoldPackageSubscriptions- 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.read
Description (from the contract)
Uses a fixed-time effective entitlement projection. Future scheduled entitlements do not hide the currently effective revision. Each subsequent page reuses all three values from the endpoint-, tenant-, and owner-bound signed cursor, so later entitlement backfills, renewals, or cancellations cannot create mixed facts.
Parameters
listMySoldPackageSubscriptions Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Versioned base64url HMAC-SHA256 envelope bound to endpoint, target tenant, and owner user where applicable. Tampering or cross-scope reuse returns package_commerce_validation_error. |
|---|
status | query | string: active / expired / cancelled | No | Effective status at the frozen snapshot. active ends after snapshot_at; expired ends at or before snapshot_at; cancelled always follows the immutable cancelled lifecycle fact regardless of end_at. |
|---|
end_at_from | query | string(date-time) | No | Inclusive canonical UTC microsecond lower bound for end_at. |
|---|
end_at_to | query | string(date-time) | No | Exclusive canonical UTC microsecond upper bound for end_at. |
|---|
include_product_name | query | string: true / false | No | Accepts exactly one lowercase true or false. Empty, repeated, or other values return 400. Omitted or false preserves the legacy response shape. true includes product_name only when the selected effective entitlement's immutable product_snapshot.name is a JSON string, preserved without normalization. Missing, null, or non-string names are omitted. The current product catalog is never used. This projection does not change subscription membership, ordering, or the cursor's tenant, owner, time, and high-water bounds. |
|---|
page | query | integer | No | Page-jump mode (1-based, max 10000, mutually exclusive with cursor). Uses OFFSET within the same frozen snapshot and returns total. |
|---|
Responses
listMySoldPackageSubscriptions Responses| Status | Description |
|---|
200 | Stable effective-subscription projection page. Fields：items: array<Subscription> next_cursor?: string total?: integer(int64) |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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/package-commerce/subscriptions/{subscription_id}/downgrade
Downgrade a package immediately or at the next cycle
- operationId
downgradePackageSubscription- 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
Parameters
downgradePackageSubscription Parameters| Name | In | Type | Required | Description |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
downgradePackageSubscription Request body| Name | Type | Required | Description |
|---|
product_id | string(uuid) | Yes | — |
|---|
product_revision | integer(int64) | Yes | — |
|---|
period | string: month / quarter / year | Yes | — |
|---|
effective_mode | string: immediate / next_cycle | Yes | — |
|---|
site_limit | integer(int64) | Yes | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
node_limit | integer(int64) | Yes | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
Responses
downgradePackageSubscription Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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
POST /v1/package-commerce/subscriptions/{subscription_id}/renew
Renew an active package subscription
- operationId
renewPackageSubscription- 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)
If-Match is the quoted current package_subscriptions revision and is passed to the core transaction as expected_revision.
Parameters
renewPackageSubscription Parameters| Name | In | Type | Required | Description |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
renewPackageSubscription Request body| Name | Type | Required | Description |
|---|
period | string: month / quarter / year | Yes | — |
|---|
promotion | PromotionReference | No | — |
|---|
payment | BalancePayment | ProviderPayment | Yes | — |
|---|
Responses
renewPackageSubscription Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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
POST /v1/package-commerce/subscriptions/{subscription_id}/upgrade
Upgrade a package immediately or at the next cycle
- operationId
upgradePackageSubscription- 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
Parameters
upgradePackageSubscription Parameters| Name | In | Type | Required | Description |
|---|
subscription_id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
upgradePackageSubscription Request body| Name | Type | Required | Description |
|---|
product_id | string(uuid) | Yes | — |
|---|
product_revision | integer(int64) | Yes | — |
|---|
period | string: month / quarter / year | Yes | — |
|---|
effective_mode | string: immediate / next_cycle | Yes | — |
|---|
site_limit | integer(int64) | Yes | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
node_limit | integer(int64) | Yes | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
Responses
upgradePackageSubscription Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
412 | If-Match does not equal the current subscription revision. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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.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
POST /v1/package-commerce/traffic-purchases
Purchase a versioned traffic package snapshot
- operationId
purchaseTrafficPackage- 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
Parameters
purchaseTrafficPackage Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | One bounded business-action key. Exact retries preserve the original payload, target, principal, and If-Match precondition. Reuse with changed input returns idempotency_conflict. |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
purchaseTrafficPackage Request body| Name | Type | Required | Description |
|---|
product_snapshot_id | string(uuid) | Yes | — |
|---|
promotion | PromotionReference | No | — |
|---|
payment | BalancePayment | ProviderPayment | Yes | — |
|---|
Responses
purchaseTrafficPackage Responses| Status | Description |
|---|
201 | Created command result or identical committed replay. Fields：order: Order fulfillment?: Fulfillment replayed: boolean |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
409 | Idempotency, provider event, state, approval, refund, or traffic-use conflict. |
|---|
422 | Funding, promotion, arithmetic, or fulfillment policy rejected the command. |
|---|
408 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
504 | The write outcome is unknown. Retry only the exact original request with the same Idempotency-Key and If-Match value where present. |
|---|
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/package-commerce/traffic-purchases/{order_id}
Get a sanitized traffic-purchase order and grant result
- operationId
getMyTrafficPackagePurchase- 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.read
Parameters
getMyTrafficPackagePurchase Parameters| Name | In | Type | Required | Description |
|---|
order_id | path | string(uuid) | Yes | — |
|---|
Responses
getMyTrafficPackagePurchase Responses| Status | Description |
|---|
200 | Sanitized traffic order and an optional grant while provider payment is pending. Fields：order: Order grant?: TrafficGrant |
|---|
400 | Invalid JSON, UUID, enum, amount, time zone, query, cursor, or required header. |
|---|
401 | Authentication is absent or invalid. |
|---|
403 | Current scope or live permission does not authorize the operation. |
|---|
404 | Resource is absent or outside the caller's visible tenant/owner scope. |
|---|
408 | Caller cancelled the query. |
|---|
502 | Stored facts or encoded response violate the public response contract. |
|---|
503 | Query storage or required callback verification is unavailable. |
|---|
504 | Query deadline elapsed. |
|---|
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