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.

Retrieve the account-level billing subscription detail read model

GET
/scopes/{scopeId}/billing/subscriptions/{billingSubscriptionId}

Returns the account-level billing subscription read model that backs the subscription detail page (Overview / Resources / Cost breakdown / Invoices / Quotas / Activity tabs): the SubscriptionAccount record — GUID, lifecycle state, offer, spending mode, billing cycle day, payment-method label, finance owner, cost center, month-to-date / projected / last-month spend, forecast delta, credit balance, outstanding amount and optional prepaid spending limit (all money fields in ten-thousandths of the currency unit) — plus the subscription activity log entries shown on the Activity tab. The Resources, Cost, Invoices and Quotas panels are populated by their sibling endpoints (billing.billing_subscription.list, billing.cost_report/cost explorer reads, billing.invoice.list, billing.quota.list). Validation: billingSubscriptionId must identify a subscription visible to the caller within scopeId (else 404 NOT_FOUND — cross-tenant existence is never disclosed); the caller must hold at least the reader or billing role in the scope (else 403). Async & state: Synchronous read; no state change. No operation is created and no resource.updated SSE frames are emitted; state transitions caused by pause/resume commands arrive as kind 'billingSubscription' frames produced by those commands, not by this read. Errors: 401 missing/expired session; 403 role lacks billing read access in this scope; 404 unknown or invisible billingSubscriptionId; 500 internal failure assembling the read model. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. The response carries no ETag; pause does not check If-Match.

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.

billingSubscriptionId*string

Identifier of the account-level billing subscription (e.g. prod, staging, dev).

Response Body

The billing subscription detail read model (account record plus activity log).

application/json
  1. response

Read model for the billing subscription detail page — the account record plus the Activity-tab log. Resources, cost, invoices and quotas panels are fetched via their own endpoints.

account*

Account-level billing subscription record backing the detail page. All money fields (monthToDate, projectedMonthly, lastMonth, creditBalance, outstanding, spendingLimit) are bare integers in ten-thousandths of the currency unit — not Money objects.

activity*array<>

Subscription activity log entries, newest first.

curl -X GET "https://example.com/scopes/string/billing/subscriptions/string"
{  "account": {    "id": "string",    "guid": "string",    "name": "string",    "state": "ACTIVE",    "currency": "USD",    "offer": "string",    "spendingMode": "PAYG",    "billingCycleDay": 0,    "startedAt": "string",    "renewsAt": "string",    "paymentMethodLabel": "string",    "ownerEmail": "string",    "costCenter": "string",    "monthToDate": 0,    "projectedMonthly": 0,    "lastMonth": 0,    "forecastDelta": 0,    "creditBalance": 0,    "outstanding": 0,    "spendingLimit": 0  },  "activity": [    {      "id": "string",      "at": "string",      "actor": "string",      "action": "string",      "detail": "string",      "channel": "success"    }  ]}