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.

List the subscription's billing contracts (read-only history)

GET
/scopes/{scopeId}/billing/contracts

Returns the customer contracts of the active scope's subscription, newest-first, each a BillingContract with its per-SKU override lines nested, in the standard { data, meta } envelope. Keyed on the billing grain (scope_id == subscription_id). READ-ONLY: contracts are operator-managed (removed the tenant create / add-line / activate writes); historical tenant-written contracts stay listable here (CANCELLED) and are never priced. Validation: scopeId must resolve to a scope the caller can reach (unknown → 404 NOT_FOUND); page ≥ 1 and pageSize within 1..200 → else 422 VALIDATION_FAILED. RBAC: READ on billing plus the billing:read token scope, held at SUBSCRIPTION level — a grant on the path project alone is refused 403 (details.reason SUBSCRIPTION_ROLE_REQUIRED). Async & state: Synchronous read; no state change. Errors: 401 unauthenticated; 403 caller lacks subscription-level billing READ or the token scope; 404 unknown scopeId; 422 malformed pagination; 500 internal failure. Idempotency/Concurrency: Safe, cacheable; no idempotency key required.

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.

Query Parameters

page?integer

1-based page number.

Range1 <= value
Default1
pageSize?integer

Items per page (max 200).

Range1 <= value <= 200
Default50

Response Body

A page of the subscription's contracts, newest-first.

application/json
  1. 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/contracts"
{  "data": [    {      "id": "string",      "name": "string",      "status": "DRAFT",      "startsAt": "2019-08-24T14:15:22Z",      "endsAt": "2019-08-24T14:15:22Z",      "currency": "string",      "createdAt": "2019-08-24T14:15:22Z",      "lines": [        {          "id": "string",          "sku": "string",          "region": "string",          "unit": "string",          "overridePriceMinor": 0,          "maxQty": 0,          "effectiveFrom": "2019-08-24T14:15:22Z",          "effectiveTo": "2019-08-24T14:15:22Z"        }      ]    }  ],  "meta": {    "page": 1,    "pageSize": 1,    "total": 0,    "hasNext": true  }}