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 the transaction ledger
Returns the billing transaction ledger for the active tenant/subscription/project scope:
charges, payments, applied credits, refunds and pending wire transfers, newest first. This single
endpoint backs both the plain Transactions page load (billing.transaction.list) and every
search/filter/sort/pagination interaction (billing.transaction.search_filter_sort): q matches
the description, the ledger reference and the linked invoice number; type and status mirror the
UI counter filters (All / Payments / Charges / Pending approval); sort accepts createdAt and
amount. Amounts are signed integers in ten-thousandths of the currency unit — charges positive (increase the outstanding balance),
payments/credits/refunds negative. No resource state is mutated.
Validation: scopeId must reference a scope visible to the caller (unknown → NOT_FOUND);
type, status, sort, order, page, pageSize must be within their declared enums/ranges,
otherwise VALIDATION_FAILED (422); the caller needs reader-or-higher (or billing) role in the scope,
otherwise FORBIDDEN.
Async & state: Synchronous read; no state change. New ledger rows posted while the view is open
arrive as resource.updated SSE frames with kind billing.transaction.
Errors: 401 missing/expired session; 403 caller lacks billing read permission in the scope;
404 unknown scope; 422 malformed filter/pagination parameters; 429 burst polling rate-limited;
500 ledger read-model unavailable.
Idempotency/Concurrency: Safe, cacheable; no idempotency key required. Stable sort keys plus
page/pageSize make repeated reads deterministic for an unchanged ledger.
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 <= 20050type?stringFilter by ledger entry type (UI counters group payment, wire-transfer-pending and refund as "Payments").
"charge""payment""credit-applied""refund""wire-transfer-pending"status?stringFilter by settlement status (the "Pending approval" counter maps to pending-manual-approval).
"completed""pending""pending-manual-approval""failed"invoiceId?stringRestrict the ledger to entries linked to a specific invoice.
Page of transaction ledger entries 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/transactions"{ "data": [ { "id": "string", "type": "charge", "description": "string", "amount": 0, "method": "string", "status": "completed", "invoiceId": "string", "invoiceNumber": "string", "reference": "string", "createdAt": "2019-08-24T14:15:22Z", "failureReason": "string", "commitmentId": "string" } ], "meta": { "page": 1, "pageSize": 1, "total": 0, "hasNext": true }}