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 and query invoices in the active scope
Returns the invoices issued for the active tenant/subscription scope as rendered by the Invoices page on
route load: invoice number, description, billing period, subtotal/tax/total in ten-thousandths of the
subscription currency's unit, lifecycle status and issue/due dates. This single endpoint also serves the
search/filter/sort/paginate behavior (billing.invoice.search_filter_sort): the UI's status chips
(ALL / PAID / UNPAID / OVERDUE / CANCELLED) map to the status query parameter and the free-text box
maps to q (matched against invoice number and description); sort, order, page and pageSize
apply standard collection semantics. Plain list = same call with no filter parameters.
Validation: scopeId must reference a scope the caller can access (otherwise 403 FORBIDDEN);
status must be one of PAID|UNPAID|OVERDUE|CANCELLED (otherwise 422 VALIDATION_FAILED); unknown sort
keys map to 422 VALIDATION_FAILED.
Async & state: Synchronous read; no state change. No SSE frames are emitted.
Errors: 401 when unauthenticated; 403 when the caller lacks billing read access in the scope;
422 for malformed query parameters; 500 on backend read-model failure.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required.
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.
region?stringRestrict the result set to a single region.
^[a-z][a-z0-9-]{1,39}$q?stringFree-text search.
sort?stringField to sort by (entity-specific; defaults to the entity's natural order).
order?stringSort direction.
"asc""asc""desc"page?integer1-based page number.
1 <= value1pageSize?integerItems per page (max 200).
1 <= value <= 20050status?stringFilter invoices by lifecycle status (UI status chips; omit for ALL).
"PAID""UNPAID""OVERDUE""CANCELLED"Paginated collection of invoices in the active scope.
application/json- 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/invoices"{ "data": [ { "id": "inv-2026-06", "number": "STC-2026-1042", "description": "Cloud services — June 2026 (current)", "currency": "USD", "subtotal": 0, "tax": 0, "total": 0, "prepaid": 0, "prepaidNet": 0, "prepaidTax": 0, "status": "PAID", "issuedAt": "2019-08-24T14:15:22Z", "dueAt": "2019-08-24T14:15:22Z", "period": "June 2026 (current)" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}