On this page
Balances
Single account balance
GET /ledger/v1/balances
curl "http://localhost:8081/ledger/v1/balances?accountReference=1500-receivables&timePeriodType=MONTHLY&timePeriodValue=2026-07&dimensionFilters=CUSTOMER:cust-001" \
-H "X-Tenant-ID: org-84120557"
Query parameters
| Parameter | Required | Notes |
|---|---|---|
accountReference | yes | Must match NNNN-slug, e.g. 1500-receivables |
timePeriodType | yes | YEAR, TERTIAL, QUARTER, BI_MONTHLY, MONTHLY |
timePeriodValue | yes | e.g. 2026-07, 2026-Q1, 2026 |
dimensionFilters | no | A TYPE:value filter — one dimension type per query |
Response — 200 OK
{
"tenantId": "org-84120557",
"accountReference": "1500-receivables",
"timePeriod": "2026-07",
"dimensionFiltersApplied": { "CUSTOMER": "cust-001" },
"balanceMinorUnits": 125000,
"currencyUnit": "EUR",
"transactionCount": 3,
"queryTimestamp": "2026-07-23T10:00:00.000Z",
"cacheHit": true
}
balanceMinorUnits is signed and debit-positive: Σ debits − Σ credits.
Balances are pre-aggregated as transactions post — per account, period and dimension — so this call is a constant-time lookup, not a scan over the event history.
Balance summary
GET /ledger/v1/balances/summary
All accounts with a non-zero balance in the period, with opening balance, movement and closing balance.
| Parameter | Required | Notes |
|---|---|---|
timePeriodType | no | Default MONTHLY |
timePeriodValue | no | Default: current period |
accounts | no | Comma-separated codes, e.g. 2700,2704 |
Response — 200 OK
[
{
"accountReference": "1500-receivables",
"timePeriod": "2026-07",
"openingBalance": 0,
"periodMovement": 125000,
"closingBalance": 125000,
"transactionCount": 3
}
]
Bucketed balances
GET /ledger/v1/balances/buckets
One outer window, sliced into buckets — e.g. a year by quarter. The resolution must be equal to or finer than the window.
| Parameter | Required | Notes |
|---|---|---|
timePeriodType | yes | Outer window, e.g. YEAR |
timePeriodValue | yes | e.g. 2026 |
resolutionType | yes | Bucket granularity, e.g. QUARTER |
Response — 200 OK
For every account and bucket (invariant: openingBalance + movement = closingBalance):
[
{
"accountReference": "3000-sales",
"bucketLabel": "2026-Q1",
"openingBalance": 0,
"movement": -250000,
"closingBalance": -250000,
"transactionCount": 12,
"carryforwardBalance": 0
}
]
| Status | Cause |
|---|---|
400 | Invalid period, or resolutionType coarser than the window |
403 | No read access to tenant |