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.

Get one transaction with its receipt and timeline context

GET
/scopes/{scopeId}/billing/transactions/{transactionId}

Retrieves a single billing transaction for the transaction detail page: the full ledger record (signed amount in ten-thousandths of the currency unit, payment method, settlement status, processor reference, linked invoice, failure reason) plus, for wire transfers, the attached bank-transfer receipt metadata (file name, originating bank, IBAN, SWIFT reference, verification state). The status drives which actions the UI offers: failed exposes "Retry payment", pending-manual-approval exposes "Cancel transfer". The read does not mutate the resource. Validation: scopeId must be visible to the caller and transactionId must belong to that scope — unknown or cross-scope ids map to NOT_FOUND (the ledger never leaks other tenants' entries); the caller needs reader-or-higher or billing role, otherwise FORBIDDEN. Async & state: Synchronous read; no state change. Status transitions performed elsewhere (pay/retry/cancel, manual receipt approval) surface here and as resource.updated SSE frames with kind billing.transaction patching status, failureReason and receipt.verification. Errors: 401 unauthenticated; 403 caller lacks billing read permission; 404 unknown scope or transaction (including soft-deleted entries); 500 read-model unavailable. Idempotency/Concurrency: Safe, cacheable; no idempotency key required. The response carries no ETag; the transaction actions do 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.

transactionId*string

Transaction ledger entry identifier (e.g. tx-9f31ad).

Response Body

Transaction detail read model, including wire receipt metadata when present.

application/json
  1. response
data*

One entry in the billing transaction ledger. amount is in ten-thousandths of the currency unit, signed by effect on the outstanding balance: charges positive (you owe more), payments / credits / refunds negative.

receipt?|null

Bank-transfer receipt metadata; null for card/credit/invoice entries.

curl -X GET "https://example.com/scopes/string/billing/transactions/string"
{  "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"  },  "receipt": {    "fileName": "string",    "sizeKb": 0,    "uploadedAt": "2019-08-24T14:15:22Z",    "bank": "string",    "iban": "string",    "swiftRef": "string",    "verification": "awaiting-review"  }}