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.
Create (configure) a new commitment purchase
Creates a new Commitment from the commitment creation form submission: commitment type
(SAVINGS_PLAN|RESERVED), term (1yr|3yr), payment option
(ALL_UPFRONT|PARTIAL_UPFRONT|NO_UPFRONT), the committed hourly rate in ten-thousandths of the currency unit per hour, and the
list of covered services (service ids such as compute/storage/database). An optional
recommendationId links the purchase back to the advisor recommendation that pre-filled the form.
On acceptance the commitment is recorded in status QUEUED and becomes discoverable in the scoped
commitment list; billing settlement later activates it.
Validation: type/term/payment must be valid enum members; hourly must be a positive
integer (ten-thousandths of the currency unit per hour); services must be a non-empty array of known service ids (unknown id → 422
VALIDATION_FAILED); a supplied recommendationId must reference an existing recommendation in the
scope (else 404 NOT_FOUND); exceeding the scope's commitment quota maps to 409 QUOTA_EXCEEDED; caller
needs owner|admin|billing, else 403.
Async & state: Asynchronous — returns 202 with an Operation (PENDING → RUNNING →
SUCCEEDED|FAILED). The created commitment starts in status QUEUED; when settlement completes it
transitions to ACTIVE and a resource.updated SSE frame of kind billing.commitment is emitted with
a patch of status, startedAt and expiresAt.
Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scope or referenced
recommendation; 409 commitment quota exceeded for the scope; 422 field validation failure; 500
internal failure.
Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the original
202 Operation rather than purchasing twice — critical because duplicate creation incurs real spend.
No If-Match applies to creation.
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.
Idempotency-Key*stringRequired: this operation creates a new resource asynchronously, so a retry without the key would create a second one. Same key+body within 24h replays the original result; the same key with a different body is 409 CONFLICT. Keys are unique per tenant (the same key in two tenants is two different requests). An API token or service-account (bearer) caller MUST send it -- a request without it is refused with 400 IDEMPOTENCY_KEY_REQUIRED (ErrIdempotencyKeyRequired); reuse the same key on every retry of one logical request. A console session gets one from the edge.
uuidapplication/json- body
The commitment creation form submission payload.
type*CommitmentTypeCommitment product kind (Savings Plan / Reserved Instance).
"SAVINGS_PLAN""RESERVED"term*CommitmentTermCommitment term length.
"1yr""3yr"payment*CommitmentPaymentCommitment upfront payment option.
"ALL_UPFRONT""PARTIAL_UPFRONT""NO_UPFRONT"hourly*integerCommitted hourly rate in ten-thousandths of the currency unit per hour.
services*array<string>Covered service ids. Coverage is COMPUTE-ONLY: the only accepted id is compute (storage / network are no longer coverable). At least one required.
classScope?|Optional Savings-Plan scope to a single compute family class (e.g. GENERAL_PURPOSE); null means flexible across all eligible compute classes.
skuScope?|Reserved-Instance target: the specific compute flavor SKU (family+size) the RI covers, e.g. compute.instance.m1.large (a bare flavor name like m1.large is accepted and normalised). Required for RESERVED, ignored for SAVINGS_PLAN.
recommendationId?|Advisor recommendation id that pre-filled this purchase, when applicable.
Commitment creation accepted; the commitment is QUEUED until settlement completes.
application/json- response
A long-running operation record. GET /operations/{operationId} returns its current state.
id*stringOperation identifier, unique platform-wide.
action*stringCanonical action id that started this operation, e.g. compute.instance.create.
state*OperationStateState machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.
"PENDING""RUNNING""SUCCEEDED""FAILED""CANCELLED"resourceKind?|Kind of the target resource (matches RealtimeEvent.kind), null for resource-less actions.
resourceId?|Identifier of the target resource; null until the resource is allocated.
resourceName?|Human-readable name of the target resource captured when the operation was opened; null when unknown or the resource has been deleted (clients fall back to resourceId).
principalId?|Subject id (user id/email or service-account id) of the actor that initiated this operation, captured at the create chokepoint; null on internal/worker paths with no request-scoped principal or for historical rows. This is the real actor the Activity feed renders.
sourceIp?|Source IP address of the request that initiated this operation; null when unavailable (internal/worker paths, historical rows).
progressPercent?|Best-effort progress; null when the action does not report progress.
0 <= value <= 100error?|nullPopulated only when state is FAILED (or CANCELLED with partial rollback notes).
warning?|nullNon-fatal degradation recorded on an operation that still SUCCEEDED - the primary action completed but something explicitly requested could not be delivered (e.g. publicIp was requested at instance create but no floating IP could be assigned). On a CANCELLED create it reports that the provider resource had already been created and was kept (live and billed until deleted; details.disposition = left_in_place). Same code+message shape as error so clients render both uniformly; null when the operation ran without degradation.
startedAt?|When the worker began executing; null while PENDING.
finishedAt?|When a terminal state was reached; null while transitional.
createdAt*stringupdatedAt*stringcurl -X POST "https://example.com/scopes/string/billing/commitments" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "type": "SAVINGS_PLAN", "term": "1yr", "payment": "ALL_UPFRONT", "hourly": 0, "services": [ "string" ] }'{ "id": "string", "action": "string", "state": "PENDING", "resourceKind": "string", "resourceId": "string", "resourceName": "string", "principalId": "string", "sourceIp": "string", "progressPercent": 0, "error": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "warning": { "code": "string", "message": "string", "field": "string", "details": {}, "retryable": false }, "startedAt": "string", "finishedAt": "string", "createdAt": "string", "updatedAt": "string"}