接口详情
GET /v1/package-commerce/catalog
List package products purchasable by the authenticated tenant user
- operationId
listPublishedPackageOffers- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.read
说明（契约原文）
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.
参数
listPublishedPackageOffers 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
kind | query | string | 是 | Public catalog projection kind. This endpoint currently exposes package products only. |
|---|
group_id | query | string(uuid) | 否 | 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 | 否 | — |
|---|
cursor | query | string | 否 | 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. |
|---|
响应
listPublishedPackageOffers 响应| 状态码 | 说明 |
|---|
200 | Stable public package catalog page and current caller eligibility. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/orders
List the authenticated tenant user's package orders
- operationId
listMyPackageOrders- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.read
说明（契约原文）
Requires package_subscriptions.read. Results are constrained by both principal scope and principal user ID. tenant_id is rejected.
参数
listMyPackageOrders 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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 | 否 | Optional order product filter shared by tenant and platform order reads. |
|---|
state | query | string: created / paid / fulfilled / cancelled / refund_applied / void_applied / failed | 否 | Optional latest order state filter shared by tenant and platform order reads. |
|---|
request_id | query | string | 否 | Optional X-Request-ID the order was created with, so a buyer can confirm the outcome of the original command. |
|---|
响应
listMyPackageOrders 响应| 状态码 | 说明 |
|---|
200 | Stable keyset page ordered by created_at and order UUID descending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/orders/{order_id}
Get one visible package order
- operationId
getMyPackageOrder- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.read
说明（契约原文）
A foreign-tenant or different-owner order returns the same 404 as an unknown order and does not disclose existence.
参数
getMyPackageOrder 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_id | path | string(uuid) | 是 | — |
|---|
响应
getMyPackageOrder 响应| 状态码 | 说明 |
|---|
200 | Sanitized visible order. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/orders/{order_id}/events
List sanitized order state events in revision order
- operationId
listMyPackageOrderEvents- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.read
说明（契约原文）
Event payload, actor, request/trace IDs, approval IDs, ledger IDs, holds, provider data, and digests are deliberately omitted.
参数
listMyPackageOrderEvents 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_id | path | string(uuid) | 是 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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. |
|---|
响应
listMyPackageOrderEvents 响应| 状态码 | 说明 |
|---|
200 | Stable event page ordered by revision ascending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/provider-callbacks/{provider}
Authenticate and apply one raw payment-provider callback
- operationId
applyVerifiedPaymentProviderCallback- 认证
- 所需权限
契约没有单独标注权限码，权限要求见下方说明与 403 响应。
说明（契约原文）
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.
参数
applyVerifiedPaymentProviderCallback 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
provider | path | string | 是 | — |
|---|
X-CDNCA-Callback-Version | header | string | 是 | Exactly one value selecting callback signature version 1. |
|---|
X-CDNCA-Callback-Key-ID | header | string | 是 | Exactly one configured key identifier bound to the provider and provider account. |
|---|
X-CDNCA-Callback-Timestamp | header | string | 是 | Exactly one canonical base-10 Unix-seconds value that fits signed int64. |
|---|
X-CDNCA-Callback-Signature | header | string | 是 | Exactly one v1= prefixed canonical base64url-no-padding encoding of the 32-byte HMAC-SHA256. |
|---|
X-Request-ID | header | string | 否 | — |
|---|
traceparent | header | string | 否 | — |
|---|
请求体
application/json · 必填：是
applyVerifiedPaymentProviderCallback 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
version | integer | 是 | — |
|---|
provider_account_id | string | 是 | — |
|---|
external_event_id | string | 是 | — |
|---|
external_payment_id | string | 是 | — |
|---|
event_kind | string: payment_succeeded / payment_failed / refund_succeeded / void_succeeded | 是 | — |
|---|
amount_minor | integer(int64) | 是 | — |
|---|
currency | string | 是 | — |
|---|
occurred_at | string(date-time) | 是 | — |
|---|
响应
applyVerifiedPaymentProviderCallback 响应| 状态码 | 说明 |
|---|
200 | Normalized provider event processed or replayed. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/purchases
Purchase a package subscription for the authenticated tenant user
- operationId
purchasePackageSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
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.
参数
purchasePackageSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
purchasePackageSubscription 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer(int64) | 是 | — |
|---|
period | string: month / quarter / year | 是 | — |
|---|
site_limit | integer(int64) | 是 | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
node_limit | integer(int64) | 是 | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
timezone | string | 是 | — |
|---|
cycle_policy | object | object | 是 | — |
|---|
traffic_factor | TrafficFactor | 是 | — |
|---|
promotion | PromotionReference | 否 | — |
|---|
payment | BalancePayment | ProviderPayment | 是 | — |
|---|
响应
purchasePackageSubscription 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/reseller/customers/{customer_scope_id}/orders
A reseller lists one of its customers' package orders
- operationId
resellerListCustomerOrders- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.read
说明（契约原文）
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.
参数
resellerListCustomerOrders 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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 | 否 | Optional order product filter shared by tenant and platform order reads. |
|---|
state | query | string: created / paid / fulfilled / cancelled / refund_applied / void_applied / failed | 否 | Optional latest order state filter shared by tenant and platform order reads. |
|---|
request_id | query | string | 否 | Optional X-Request-ID the order was created with, so a buyer can confirm the outcome of the original command. |
|---|
响应
resellerListCustomerOrders 响应| 状态码 | 说明 |
|---|
200 | Stable keyset page ordered by created_at and order UUID descending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/purchases
A reseller buys one of its packages for its own customer
- operationId
resellerPurchaseForCustomer- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
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.
参数
resellerPurchaseForCustomer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
resellerPurchaseForCustomer 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
owner_user_id | string(uuid) | 是 | — |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer(int64) | 是 | — |
|---|
period | string: month / quarter / year | 是 | — |
|---|
响应
resellerPurchaseForCustomer 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions
A reseller lists one of its customers' package subscriptions
- operationId
resellerListCustomerSubscriptions- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.read
说明（契约原文）
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).
参数
resellerListCustomerSubscriptions 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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 | 否 | 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) | 否 | Inclusive canonical UTC microsecond lower bound for end_at. |
|---|
end_at_to | query | string(date-time) | 否 | Exclusive canonical UTC microsecond upper bound for end_at. |
|---|
include_product_name | query | string: true / false | 否 | 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 | 否 | Page-jump mode (1-based, max 10000, mutually exclusive with cursor). |
|---|
响应
resellerListCustomerSubscriptions 响应| 状态码 | 说明 |
|---|
200 | Stable effective-subscription projection page. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/cancel
A reseller cancels its customer's subscription
- operationId
resellerCancelCustomerSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
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.
参数
resellerCancelCustomerSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
resellerCancelCustomerSubscription 响应| 状态码 | 说明 |
|---|
201 | Cancelled subscription or exact idempotent replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
↑ 回到列表
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- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
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.
参数
resellerDowngradeForCustomer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
resellerDowngradeForCustomer 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer | 是 | — |
|---|
period | string: month / quarter / year | 是 | — |
|---|
响应
resellerDowngradeForCustomer 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
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- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
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).
参数
resellerRenewForCustomer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
resellerRenewForCustomer 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
period | string: month / quarter / year | 是 | — |
|---|
响应
resellerRenewForCustomer 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/suspend
Suspend one package subscription as the customer's reseller
- operationId
resellerSuspendCustomerSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
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.
参数
resellerSuspendCustomerSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
resellerSuspendCustomerSubscription 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
reason | string | 是 | — |
|---|
响应
resellerSuspendCustomerSubscription 响应| 状态码 | 说明 |
|---|
200 | The subscription after the change (or unchanged when already in that state), or an exact idempotent replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
POST /v1/package-commerce/reseller/customers/{customer_scope_id}/subscriptions/{subscription_id}/unsuspend
Unsuspend one package subscription as the customer's reseller
- operationId
resellerUnsuspendCustomerSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
Publishes the subscription's sites and forwards again at once. Unsuspending a subscription that is not suspended succeeds without a change.
参数
resellerUnsuspendCustomerSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
响应
resellerUnsuspendCustomerSubscription 响应| 状态码 | 说明 |
|---|
200 | The subscription after the change (or unchanged when already in that state), or an exact idempotent replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。
↑ 回到列表
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- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：reseller.customers.manage
说明（契约原文）
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.
参数
resellerUpgradeForCustomer 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
customer_scope_id | path | string(uuid) | 是 | — |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
resellerUpgradeForCustomer 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer | 是 | — |
|---|
period | string: month / quarter / year | 是 | — |
|---|
响应
resellerUpgradeForCustomer 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/subscriptions
List effective sold-subscription projections owned by the current user
- operationId
listMySoldPackageSubscriptions- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.read
说明（契约原文）
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.
参数
listMySoldPackageSubscriptions 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
limit | query | integer | 否 | — |
|---|
cursor | query | string | 否 | 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 | 否 | 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) | 否 | Inclusive canonical UTC microsecond lower bound for end_at. |
|---|
end_at_to | query | string(date-time) | 否 | Exclusive canonical UTC microsecond upper bound for end_at. |
|---|
include_product_name | query | string: true / false | 否 | 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 | 否 | Page-jump mode (1-based, max 10000, mutually exclusive with cursor). Uses OFFSET within the same frozen snapshot and returns total. |
|---|
响应
listMySoldPackageSubscriptions 响应| 状态码 | 说明 |
|---|
200 | Stable effective-subscription projection page. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/subscriptions/{subscription_id}/downgrade
Downgrade a package immediately or at the next cycle
- operationId
downgradePackageSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
参数
downgradePackageSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
downgradePackageSubscription 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer(int64) | 是 | — |
|---|
period | string: month / quarter / year | 是 | — |
|---|
effective_mode | string: immediate / next_cycle | 是 | — |
|---|
site_limit | integer(int64) | 是 | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
node_limit | integer(int64) | 是 | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
响应
downgradePackageSubscription 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/subscriptions/{subscription_id}/renew
Renew an active package subscription
- operationId
renewPackageSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
If-Match is the quoted current package_subscriptions revision and is passed to the core transaction as expected_revision.
参数
renewPackageSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
renewPackageSubscription 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
period | string: month / quarter / year | 是 | — |
|---|
promotion | PromotionReference | 否 | — |
|---|
payment | BalancePayment | ProviderPayment | 是 | — |
|---|
响应
renewPackageSubscription 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/subscriptions/{subscription_id}/upgrade
Upgrade a package immediately or at the next cycle
- operationId
upgradePackageSubscription- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
参数
upgradePackageSubscription 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | Quoted positive decimal package subscription revision. |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
upgradePackageSubscription 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer(int64) | 是 | — |
|---|
period | string: month / quarter / year | 是 | — |
|---|
effective_mode | string: immediate / next_cycle | 是 | — |
|---|
site_limit | integer(int64) | 是 | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
node_limit | integer(int64) | 是 | -1 means unlimited; otherwise 0 through 1,000,000,000. |
|---|
响应
upgradePackageSubscription 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/package-commerce/traffic-purchases
Purchase a versioned traffic package snapshot
- operationId
purchaseTrafficPackage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
参数
purchaseTrafficPackage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | 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 | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
purchaseTrafficPackage 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
product_snapshot_id | string(uuid) | 是 | — |
|---|
promotion | PromotionReference | 否 | — |
|---|
payment | BalancePayment | ProviderPayment | 是 | — |
|---|
响应
purchaseTrafficPackage 响应| 状态码 | 说明 |
|---|
201 | Created command result or identical committed replay. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/package-commerce/traffic-purchases/{order_id}
Get a sanitized traffic-purchase order and grant result
- operationId
getMyTrafficPackagePurchase- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.read
参数
getMyTrafficPackagePurchase 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_id | path | string(uuid) | 是 | — |
|---|
响应
getMyTrafficPackagePurchase 响应| 状态码 | 说明 |
|---|
200 | Sanitized traffic order and an optional grant while provider payment is pending. 字段：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. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表