Operation details
GET /v1/traffic-packages/balances
List current-user balances grouped by metering bucket
- operationId
listMyTrafficPackageBalances- 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：traffic_packages.read
Description (from the contract)
All quantities are integer bytes. Only migration-051 grants purchased by the current user participate in the aggregation.
Parameters
listMyTrafficPackageBalances Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
Responses
listMyTrafficPackageBalances Responses| Status | Description |
|---|
200 | Current-user byte balances grouped by metering bucket. Fields：items: array<Balance> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
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/traffic-packages/grants
List grants purchased by the authenticated tenant user
- operationId
listMyTrafficPackageGrants- 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：traffic_packages.read
Description (from the contract)
Both tenant and owner user are derived from the current principal. tenant_id is rejected.
Parameters
listMyTrafficPackageGrants Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
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. |
|---|
status | query | string: active / exhausted / expired / reversed | No | Only grants whose current status matches; filtered before paging, and total follows the filter. A cursor is bound to the status it was issued for. |
|---|
Responses
listMyTrafficPackageGrants Responses| Status | Description |
|---|
200 | Grants visible under the derived or explicit tenant scope. Fields：items: array<Grant> next_cursor?: string total?: integer(int64) |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
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/traffic-packages/grants/{grant_id}
Read one grant purchased by the authenticated tenant user
- operationId
getMyTrafficPackageGrant- 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：traffic_packages.read
Description (from the contract)
Same tenant and owner scope as the grant list; a grant of another tenant or user is 404. No query parameters are accepted.
Parameters
getMyTrafficPackageGrant Parameters| Name | In | Type | Required | Description |
|---|
grant_id | path | string(uuid) | Yes | — |
|---|
Responses
getMyTrafficPackageGrant Responses| Status | Description |
|---|
200 | One traffic package grant. Fields：id: string(uuid) owner_user_id?: object product_snapshot_id: string(uuid) product_name: string allowed_package_names: array<string> price_minor: integer(int64) granted_bytes: integer(int64) remaining_bytes: integer(int64) starts_at: string(date-time) expires_at: string(date-time) expiry_timezone: string priority: integer currency: string metering_scope: string metering_version: string status: string: active / exhausted / expired / reversed revision: integer(int64) created_at: string(date-time) updated_at: string(date-time) |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
404 | Resource is absent or not visible in the authorized scope. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
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/traffic-packages/products
List current products visible to the authenticated tenant
- operationId
listAvailableTrafficPackageProducts- 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：traffic_packages.read
Description (from the contract)
Tenant scope is derived from the current principal. The result includes global products and products targeted to that tenant whose latest lifecycle fact is enabled. Disabled products remain in admin and history.
Parameters
listAvailableTrafficPackageProducts Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
Responses
listAvailableTrafficPackageProducts Responses| Status | Description |
|---|
200 | Current products or immutable revision history. Fields：items: array<Product> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
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/traffic-packages/purchases
Traffic package purchase boundary
- operationId
purchaseTrafficPackageThroughCommerce- 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)
Tenant and buyer are derived from the current principal. This route never calls trafficpackage.Grant directly. Until a reviewed adapter can invoke packagecommercehttp.Service.PurchaseTraffic unchanged, it always returns traffic_package_purchase_unavailable (503) and performs no write.
Parameters
purchaseTrafficPackageThroughCommerce Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
X-Request-ID | header | string | Yes | — |
|---|
traceparent | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
purchaseTrafficPackageThroughCommerce Request body| Name | Type | Required | Description |
|---|
product_snapshot_id | string(uuid) | Yes | — |
|---|
promotion | PromotionReference | No | — |
|---|
payment | BalancePayment | ProviderPayment | Yes | — |
|---|
Responses
purchaseTrafficPackageThroughCommerce Responses| Status | Description |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
503 | Reviewed package-commerce purchase wiring is absent; no write occurred. |
|---|
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/traffic-packages/usage-events
List current-user consumption and refund results
- operationId
listMyTrafficPackageUsageEvents- 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：traffic_packages.read
Description (from the contract)
Only consume and refund operations are visible. Internal source event keys, request/trace IDs, product snapshots, ledger IDs, billing IDs, and provider payloads are omitted.
Parameters
listMyTrafficPackageUsageEvents Parameters| Name | In | Type | Required | Description |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
operation | query | string: consume / refund | No | — |
|---|
grant_id | query | string(uuid) | No | 只看该流量包（授予）的分录，amount_bytes 只计该包承担的部分。 |
|---|
Responses
listMyTrafficPackageUsageEvents Responses| Status | Description |
|---|
200 | Sanitized current-user usage and refund results. Fields：items: array<UsageEvent> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
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/traffic-packages/usage-events/{event_id}/allocations
List bounded allocation details for one visible usage event
- operationId
listMyTrafficPackageUsageAllocations- 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：traffic_packages.read
Description (from the contract)
Tenant and owner user are derived from the authenticated principal. The command receipt never embeds allocations; clients page this immutable projection explicitly.
Parameters
listMyTrafficPackageUsageAllocations Parameters| Name | In | Type | Required | Description |
|---|
event_id | path | string(uuid) | Yes | — |
|---|
limit | query | integer | No | — |
|---|
cursor | query | string | No | Opaque HMAC-signed cursor bound to endpoint, principal scope, target tenant, owner user, UTC-microsecond snapshot_at, and the applicable migration-066 catalog/usage snapshot_version or grant-state watermark. |
|---|
Responses
listMyTrafficPackageUsageAllocations Responses| Status | Description |
|---|
200 | Bounded page of immutable allocation details for one visible usage event. Fields：items: array<Allocation> next_cursor?: string |
|---|
400 | Malformed headers, query, JSON, UUID, cursor, unit, or range. |
|---|
401 | Ordinary session authentication is required. |
|---|
403 | Principal scope or required permission is absent. |
|---|
408 | Read context was cancelled. |
|---|
502 | Stored or core facts did not satisfy the public response contract. |
|---|
503 | Read storage is unavailable. |
|---|
504 | Read deadline expired. |
|---|
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