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.
Release one seat of an entitlement back to the pool
Gives ONE seat back. The ENTITLEMENT is untouched: releasing a seat never cancels it, never expires
it and never stops the billing — the pool keeps its quantity and keeps being charged for it,
because the customer bought the pool rather than the occupancy.
Validation: resourceType/resourceId must identify a resource currently HOLDING a seat of this
entitlement, else 404 NOT_FOUND. Caller needs billing:write, else 403.
Async & state: Synchronous.
Errors: 401; 403; 404 unknown scope, entitlement, or no open assignment for that resource; 422
malformed body; 500.
Idempotency/Concurrency: Releasing an already-released seat is a 404.
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.
entitlementId*stringThe subscription-scoped entitlement's id.
application/json- body
resourceType*EntitlementResourceTypeThe kind of resource an entitlement seat can be applied to. Extensible — new kinds (a Kubernetes cluster) are added here without a data migration.
"instance""volume""load_balancer"resourceId*stringMust be a LIVE resource of the caller's own tenant; anything else is 404.
The seat is back in the pool; the entitlement is returned with updated seat counts.
application/json- response
data*A subscription-scoped add-on or licence the account HOLDS, independent of any one resource. Unlike an
instance-scoped add-on (which is born with a VM and dies with it), an entitlement survives the
deletion of every resource it was applied to and can be re-applied elsewhere.
quantity is a POOL OF SEATS: an entitlement with quantity: N may be assigned to N DISTINCT
resources at the same time. Billing charges quantity units per period whether or not every seat is
currently assigned — the customer bought the pool, not the occupancy.
curl -X POST "https://example.com/scopes/string/billing/entitlements/string/actions/release" \ -H "Content-Type: application/json" \ -d '{ "resourceType": "instance", "resourceId": "string" }'{ "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" } }}