接口详情
List all package orders for one explicit tenant
- operationId
listTenantPackageOrdersAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
参数
listTenantPackageOrdersAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Target tenant access-scope UUID; platform routes never infer it. |
|---|
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. |
|---|
operation | query | string: upgrade / downgrade | 否 | Optional platform-only filter for package upgrade or downgrade orders. |
|---|
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. |
|---|
响应
listTenantPackageOrdersAsPlatform 响应| 状态码 | 说明 |
|---|
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 one order in an explicit tenant scope
- operationId
getTenantPackageOrderAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
参数
getTenantPackageOrderAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_id | path | string(uuid) | 是 | — |
|---|
tenant_id | query | string(uuid) | 是 | Target tenant access-scope UUID; platform routes never infer it. |
|---|
响应
getTenantPackageOrderAsPlatform 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
List sanitized events for one tenant order
- operationId
listTenantPackageOrderEventsAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
参数
listTenantPackageOrderEventsAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_id | path | string(uuid) | 是 | — |
|---|
tenant_id | query | string(uuid) | 是 | Target tenant access-scope UUID; platform routes never infer it. |
|---|
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. |
|---|
响应
listTenantPackageOrderEventsAsPlatform 响应| 状态码 | 说明 |
|---|
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/admin/package-commerce/orders/{order_id}/refund
Apply an approved partial or cumulative refund
- operationId
refundPackageOrder- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
说明（契约原文）
Requires a platform principal with billing.adjustments.manage and an explicit tenant_id. The core requires a matching unexpired, unused two-person approval fact; this endpoint neither creates nor weakens that approval. gross_amount_minor is the gross amount for this refund action.
参数
refundPackageOrder 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_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 · 必填：是
refundPackageOrder 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
gross_amount_minor | integer(int64) | 是 | — |
|---|
revoke_entitlement | boolean | 是 | — |
|---|
approval_id | string(uuid) | string | 否 | Optional. Refunds no longer require a second administrator's approval. When supplied it must be a canonical UUID of an unexpired, unused manual approval for this order and operation; it is then validated and consumed as before. An empty string is treated as absent. |
|---|
响应
refundPackageOrder 响应| 状态码 | 说明 |
|---|
200 | Applied 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 重试。
↑ 回到列表
POST /v1/admin/package-commerce/orders/{order_id}/void
Void an eligible order using a one-time approval fact
- operationId
voidPackageOrder- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
说明（契约原文）
Requires billing.adjustments.manage and an explicit tenant_id. The approval must match the order, tenant, operation, executor, and validity window. Existing refunds or a consumed approval remain hard failures.
参数
voidPackageOrder 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_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 · 必填：是
voidPackageOrder 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
approval_id | string(uuid) | string | 否 | Optional. Voids no longer require a second administrator's approval. When supplied it is validated and consumed as before; an empty string is treated as absent. |
|---|
响应
voidPackageOrder 响应| 状态码 | 说明 |
|---|
200 | Applied 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. |
|---|
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/admin/package-commerce/sold
List sold packages across tenants
- operationId
listAdminSoldPackages- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
说明（契约原文）
Requires a platform-scope principal. Empty optional parameters must be omitted; duplicate and unknown parameters are rejected. Product options include all sold products independent of filters, without a 100-item cap. Names come from the effective immutable product snapshot. User display IDs come from users.display_id. A subscription ID is its actual UUID, never its revision. Expiry week is the next 7 days; month is the next calendar month, both excluding already expired records. Expired includes ends_at equal to the query time. Status is the stored lifecycle status; an expired active subscription still has lifecycle_status active. Usage is currently null because the commerce read model has no authoritative settled per-cycle counter; unknown usage matches neither exhausted nor remaining. A traffic limit of -1 means unlimited. CNAME searches current and last-known-good hostname claims associated with the subscription or one of its sites. Search values are literal case-insensitive substrings, not SQL patterns.
参数
listAdminSoldPackages 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
page | query | integer | 否 | — |
|---|
limit | query | integer | 否 | — |
|---|
expiry | query | string: all / month / week / expired | 否 | — |
|---|
product_id | query | string(uuid) | 否 | — |
|---|
sort | query | string: created_at_desc / ends_at_asc | 否 | — |
|---|
status | query | string: all / enabled / disabled / active / cancelled | 否 | — |
|---|
usage | query | string: all / exhausted / remaining | 否 | — |
|---|
user_id | query | string | 否 | Exact owner UUID or positive decimal user display ID. |
|---|
q | query | string | 否 | Literal substring of the package snapshot name or (when not all digits) of the subscription UUID; a positive decimal also matches the package display ID exactly. |
|---|
cname | query | string | 否 | — |
|---|
响应
listAdminSoldPackages 响应| 状态码 | 说明 |
|---|
200 | Globally filtered page with count and complete sold-product options. 字段：items: array<SoldPackage> count: integer(int64) products: array<object> |
|---|
400 | Invalid parameters (package_commerce_validation_error). |
|---|
401 | Authentication required. |
|---|
403 | Platform scope and billing.adjustments.manage required. |
|---|
408 | Request cancelled. |
|---|
502 | Invalid stored facts or oversized response. |
|---|
503 | Read store unavailable. |
|---|
504 | Query deadline exceeded. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
POST /v1/admin/package-commerce/sold/commands
- operationId
administerSoldPackages- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
Executes all selected items in one transaction. The live session and RBAC are rechecked, including replay. A changed body under an existing key is rejected. Editing appends an entitlement snapshot without rewriting the purchased catalog version or historical prices. Enable/disable is independent of cancellation. Safe deletion rejects live resources; cascade deletion uses audited resource deletion and edge publication. Neither mode refunds money; unsettled orders, held balances and scheduled entitlements block deletion. Sync copies only selected fields to bound websites and L4 forwarding resources, then persists signed edge publication, rollout and node command outbox. Publication receipts are polled separately and command success does not imply every node has applied it.
参数
administerSoldPackages 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
administerSoldPackages 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
action | string: edit / enable / disable / delete / sync | 是 | — |
|---|
items | array<object> | 是 | — |
|---|
config | SoldConfig | 否 | — |
|---|
ends_at | string(date-time) | 否 | — |
|---|
delete_mode | string: safe / cascade | 否 | — |
|---|
sync_fields | array<string: line_group / cname_domain / cname_mode> | 否 | — |
|---|
响应
administerSoldPackages 响应| 状态码 | 说明 |
|---|
200 | Persisted command or exact idempotent replay. 字段：items: array<SoldDetail> publications: array<SoldPublication> replayed: boolean |
|---|
400 | Invalid or duplicate fields/items; edit requires one item and a full config. |
|---|
401 | A live platform session is required. |
|---|
403 | Required package/resource/DNS/publication permission denied. |
|---|
409 | package_sold_dependencies, package_sold_financial_dependencies, package_sold_setting_unsupported, package_sold_invalid_state or idempotency_conflict. |
|---|
412 | revision_conflict; no item was modified. |
|---|
503 | package_sold_runtime_unavailable; no item was modified. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。401 检查凭据格式、是否过期或被轮换。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。503 依赖暂不可用：稍后用原 Idempotency-Key 重试。
↑ 回到列表
GET /v1/admin/package-commerce/sold/{subscription_id}
- operationId
getAdminSoldPackage- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
参数
getAdminSoldPackage 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
响应
getAdminSoldPackage 响应| 状态码 | 说明 |
|---|
200 | Effective sold snapshot and complete authorized reference options. 字段：id: string(uuid) tenant_scope_id: string(uuid) owner_user_id: string(uuid) revision: integer enabled: boolean deleted: boolean ends_at: string(date-time) config: SoldConfig options: object |
|---|
403 | Platform read permission required. |
|---|
404 | Subscription not found. |
|---|
失败时怎么办
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。
↑ 回到列表
GET /v1/admin/package-commerce/sold/{subscription_id}/sync
- operationId
getAdminSoldPackageSync- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
参数
getAdminSoldPackageSync 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
响应
getAdminSoldPackageSync 响应| 状态码 | 说明 |
|---|
200 | Latest 20 publications with authoritative rollout and latest node attempt counts. 字段：publications: array<object> |
|---|
403 | Platform read permission required. |
|---|
404 | Subscription not found. |
|---|
失败时怎么办
403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。
↑ 回到列表
List effective sold subscriptions for one explicit tenant
- operationId
listSoldPackageSubscriptionsAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
说明（契约原文）
Uses the fixed-time effective entitlement projection. Each subsequent page reuses all three values from the endpoint- and tenant-bound signed cursor, so later entitlement backfills, renewals, or cancellations cannot create mixed facts.
参数
listSoldPackageSubscriptionsAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
tenant_id | query | string(uuid) | 是 | Target tenant access-scope UUID; platform routes never infer it. |
|---|
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. |
|---|
响应
listSoldPackageSubscriptionsAsPlatform 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表
Open a package subscription for an active tenant member without an order
- operationId
openPackageSubscriptionAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
Creates the subscription, immutable revision-one state, and active manual_open entitlement atomically. It never fabricates an order, payment, or fulfillment. Unknown outcomes may be retried only with the exact original body and Idempotency-Key.
参数
openPackageSubscriptionAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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 · 必填：是
openPackageSubscriptionAsPlatform 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
owner_user_id | string(uuid) | 是 | — |
|---|
product_id | string(uuid) | 是 | — |
|---|
product_revision | integer(int64) | 是 | — |
|---|
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. |
|---|
duration | string: month / quarter / year | 否 | — |
|---|
end_at | string(date-time) | 否 | — |
|---|
timezone | string | 是 | — |
|---|
cycle_policy | object | object | 是 | — |
|---|
traffic_factor | TrafficFactor | 是 | — |
|---|
响应
openPackageSubscriptionAsPlatform 响应| 状态码 | 说明 |
|---|
201 | Subscription and entitlement created, or an identical committed replay returned. 字段：subscription_id: string(uuid) tenant_scope_id: string(uuid) owner_user_id: string(uuid) product_id: string(uuid) product_revision: integer(int64) starts_at: string(date-time) ends_at: string(date-time) lifecycle_status: string revision: integer(int64) 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. |
|---|
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 重试。
↑ 回到列表
Cancel a tenant subscription as administrator
- operationId
cancelPackageSubscriptionAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
Physical deletion is not supported by cancellation. Use sold package commands for independent enable/disable and audited deletion.
参数
cancelPackageSubscriptionAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
subscription_id | path | string(uuid) | 是 | — |
|---|
If-Match | header | string | 是 | — |
|---|
Idempotency-Key | header | string | 是 | — |
|---|
X-Request-ID | header | string | 是 | — |
|---|
traceparent | header | string | 是 | — |
|---|
请求体
application/json · 必填：是
cancelPackageSubscriptionAsPlatform 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
响应
cancelPackageSubscriptionAsPlatform 响应| 状态码 | 说明 |
|---|
201 | Cancelled subscription or exact idempotent replay. 字段：subscription: object intent?: object |
|---|
400 | Invalid request. |
|---|
403 | Permission denied. |
|---|
404 | Subscription not found. |
|---|
409 | Invalid subscription state or idempotency conflict. |
|---|
412 | Revision conflict. |
|---|
失败时怎么办
400 按字段说明修正参数或请求体再发；不要原样重试。403 检查 Key 范围与所有者当前权限、当前租户作用域；不要换更高权限账号绕过。404 资源不存在或不属于当前租户。409 先回读资源当前状态；同一操作重试保持原 Idempotency-Key 和原请求内容。412 版本已变：回读最新 ETag 后重新判断，再带新的 If-Match 提交。
↑ 回到列表
Suspend one package subscription as an administrator
- operationId
suspendPackageSubscriptionAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.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.
参数
suspendPackageSubscriptionAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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 · 必填：是
suspendPackageSubscriptionAsPlatform 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
reason | string | 是 | — |
|---|
响应
suspendPackageSubscriptionAsPlatform 响应| 状态码 | 说明 |
|---|
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 和原请求内容。
↑ 回到列表
Unsuspend one package subscription as an administrator
- operationId
unsuspendPackageSubscriptionAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：package_subscriptions.manage
说明（契约原文）
Publishes the subscription's sites and forwards again at once. Unsuspending a subscription that is not suspended succeeds without a change.
参数
unsuspendPackageSubscriptionAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
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 · 必填：是
unsuspendPackageSubscriptionAsPlatform 请求体| 名称 | 类型 | 必填 | 说明 |
|---|
tenant_id | string(uuid) | 是 | — |
|---|
响应
unsuspendPackageSubscriptionAsPlatform 响应| 状态码 | 说明 |
|---|
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 和原请求内容。
↑ 回到列表
Get one sanitized traffic-purchase result for an explicit tenant
- operationId
getTenantTrafficPackagePurchaseAsPlatform- 认证
- 登录会话：主控登录后的 Bearer 会话，由客户本人在自己的主控里使用；插件不能要求客户交出会话。
- 所需权限
全部需要：billing.adjustments.manage
说明（契约原文）
The platform principal must name the target tenant. A purchase outside that tenant scope is indistinguishable from an unknown order.
参数
getTenantTrafficPackagePurchaseAsPlatform 参数| 名称 | 位置 | 类型 | 必填 | 说明 |
|---|
order_id | path | string(uuid) | 是 | — |
|---|
tenant_id | query | string(uuid) | 是 | Target tenant access-scope UUID; platform routes never infer it. |
|---|
响应
getTenantTrafficPackagePurchaseAsPlatform 响应| 状态码 | 说明 |
|---|
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 重试。
↑ 回到列表