GET/v1/billing/ledger

Ledger entries

Append-only ledger entries newest first with a cursor: top-ups, reservations, releases, charges, refunds, adjustments, subscription fees and invoice payments, each with the amount and what it did to the balance, the reserved and the outstanding figures. Filter on type (comma separated), a period and a reference id (for example an item id).

Scope billing.read

Query parameters

typeany

fromdate-time

todate-time

referenceIdstringmin length 1max length 60

limitintegermin 1max 200default 50

cursorstringmax length 200

Returns

2 fields of the 200 answer

dataarray of objectsrequired

14 fields

idstringrequired

typeenumrequired

TOP_UPRESERVATIONRELEASECHARGEREFUNDADJUSTMENTSUBSCRIPTION_FEEINVOICE_PAYMENT

amountCentsintegerrequired

currencystringrequired

balanceDeltaCentsintegerrequired

reservedDeltaCentsintegerrequired

outstandingDeltaCentsintegerrequired

referenceTypeenum or nullrequired

itempostbatchruninvoicepayment

referenceIdstring or nullrequired

descriptionstring or nullrequired

metadataobjectrequired

17 fields

modeenum

PREPAIDTRIALINVOICE

listAmountCentsinteger

productIdstring

finishstring

destinationstring

runIdstring or null

postbatchIdstring or null

postflowIdstring or null

subscriptionIdstring

planIdstring

monthstring

invoiceVatboolean

invoiceNumberstring

creditNoteOfstring

reasonstring

methodenum

BANK_TRANSFEROTHER

paidAtdate-time

actorTypeenumrequired

USERAPI_KEYADMINSYSTEM

actorIdstring or nullrequired

createdAtdate-timerequired

nextCursorstring or nullrequired

Responses

200Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.billing.ledger({ query: { limit: 20, }, });

{ "data": [ { "id": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "type": "TOP_UP", "amountCents": 1250, "currency": "EUR", "balanceDeltaCents": 1250, "reservedDeltaCents": 1250, "outstandingDeltaCents": 1250, "referenceType": "item", "referenceId": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "description": "Welcome card for new customers", "metadata": { "mode": "PREPAID", "listAmountCents": 1250, "productId": "prd_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "finish": "silk", "destination": "Example", "runId": "run_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "postbatchId": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "postflowId": "pf_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "subscriptionId": "sub_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "planId": "pln_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "month": "Example", "invoiceVat": false, "invoiceNumber": "Example", "creditNoteOf": "Example", "reason": "Example", "method": "BANK_TRANSFER", "paidAt": "2026-10-16T09:14:02.000Z" }, "actorType": "USER", "actorId": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "createdAt": "2026-10-16T09:14:02.000Z" } ], "nextCursor": "Example" }

{ "type": "https://docs.postbuddy.nl/errors/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Validation failed", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "errors": [ { "field": "recipient.postalCode", "code": "invalid_string", "message": "Invalid postal code" } ] }