Billing & FinOps

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.

Renew a commitment (queue a successor term)

POST
/scopes/{scopeId}/billing/commitments/{commitmentId}/actions/renew

Renews the selected Commitment (the "Renew" action on the commitment detail page). Renewal creates a successor Commitment (renewedFromId = the path commitment) that copies its locked economics (type, term, payment option, scope, hourly committed rate, discount, upfront) and starts at max(now, expiresAt) of the path commitment, so coverage can continue without an on-demand gap. The renewed commitment itself is never changed — its expiresAt does not move; its renewalId now points at the successor. Payment gate: a successor with an upfront amount is PENDING_ACTIVATION and covers nothing until a platform operator confirms the linked upfront charge (a charge Transaction carrying the successor's commitmentId); its term then starts at max(confirmation, expiresAt of the renewed commitment). A NO_UPFRONT successor is ACTIVE immediately but covers usage only from its start. Result: 202 with a SUCCEEDED Operation whose resourceId is the successor's id (not the path commitment). Validation: the commitment must exist and be visible in the active scope (else 404 NOT_FOUND). 409 CONFLICT when its status is not ACTIVE, EXPIRING or EXPIRED (QUEUED, PENDING_ACTIVATION, REJECTED), when its term has not started yet (a queued renewal cannot itself be renewed), or when it already has a live renewal (renewalId set — pending payment or scheduled). Caller must hold owner|admin|billing on the scope, else 403. Errors: 401 unauthenticated; 403 insufficient role; 404 unknown scope or commitment; 409 see above; 422 malformed request; 400 IDEMPOTENCY_KEY_REQUIRED when an API token or service-account caller sends no Idempotency-Key; 500 internal failure. Idempotency/Concurrency: Idempotency-Key is required; replaying the same key returns the same successor (202, same resourceId) instead of creating a second renewal — also after that successor was REJECTED (renew again with a new key). Concurrent renewals of one commitment are serialised; at most one live successor can exist.

Authorization

bearerToken
headerAuthorizationBearer <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.

Path Parameters

scopeId*string

Opaque ownership+authorization scope resolving to tenant + subscription + project.

commitmentId*string

Identifier of the commitment within the active scope.

Header Parameters

Idempotency-Key*string

Required: 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.

Formatuuid

Response Body

Renewal accepted; track progress through the returned Operation.

application/json
  1. response

A long-running operation record. GET /operations/{operationId} returns its current state.

id*string

Operation identifier, unique platform-wide.

action*string

Canonical action id that started this operation, e.g. compute.instance.create.

state*OperationState

State machine for long-running operations. PENDING and RUNNING are transitional; the rest are terminal.

Value in"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.

Range0 <= value <= 100
error?|null

Populated only when state is FAILED (or CANCELLED with partial rollback notes).

warning?|null

Non-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*string
updatedAt*string
curl -X POST "https://example.com/scopes/string/billing/commitments/string/actions/renew" \  -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "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"}