Preview — pending review
This reference is generated from the platform API contract and is still under review. Operations, fields, and descriptions can change before publication.
List the subscription's add-on / licence entitlements
Returns the subscription-scoped entitlements the account holds (active and expired; paged with page /
pageSize, default and maximum 200), each with its
frozen unit price, its seat pool (quantity), the derived seatsUsed/seatsAvailable counts and the
list of resources currently holding a seat. This is the "licenses & entitlements" surface;
instance-create refuses subscription-scoped catalog items in favour of it.
Entitlements are keyed on the BILLING grain — the scopeId on the wire is a project id, which the
service resolves to its subscription — so the same list is returned for every project of a
subscription.
Validation: scopeId must be accessible (404 NOT_FOUND if unknown).
Async & state: Synchronous read; no state change.
Errors: 401 unauthenticated; 403 caller lacks billing:read on the scope; 404 unknown scopeId;
500 read-model failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required.
bearerTokenAuthorizationBearer <token>An API token (pc_live_…) or a service-account key (sak_live_…), created in Identity & Access Management and sent as Authorization: Bearer <token>. Requests are rate limited per credential and per tenant: every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, and a refused request gets 429 RATE_LIMITED with Retry-After.
scopeId*stringOpaque ownership+authorization scope resolving to tenant + subscription + project.
page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200). Lists that used to return every row default to the maximum, so a client that does not page keeps seeing up to 200 rows; a larger value is refused with 422.
1 <= value <= 200200The subscription's entitlements.
application/json- response
data*array<>meta*Pagination envelope metadata. List responses are always { data, meta } — never a naked array.
curl -X GET "https://example.com/scopes/string/billing/entitlements"{ "data": [ { "id": "string", "itemKind": "addon", "itemId": "string", "itemSlug": "string", "name": "string", "period": "hour", "unitPriceMinor": 0, "currency": "string", "sku": "string", "quantity": 1, "seatsUsed": 0, "seatsAvailable": 0, "state": "active", "autoRenew": true, "honoured": true, "termStartedAt": "2019-08-24T14:15:22Z", "termEndsAt": "2019-08-24T14:15:22Z", "renewsAt": "2019-08-24T14:15:22Z", "createdAt": "2019-08-24T14:15:22Z", "cancelledAt": "2019-08-24T14:15:22Z", "expiredAt": "2019-08-24T14:15:22Z", "assignments": [ { "id": "string", "resourceType": "instance", "resourceId": "string", "assignedAt": "2019-08-24T14:15:22Z" } ], "assignment": { "id": "string", "resourceType": "instance", "resourceId": "string", "assignedAt": "2019-08-24T14:15:22Z" } } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}