Account balances

Every account reports three balances. They answer three different questions, and choosing the wrong one is the most common cause of "the balance looks wrong" reports.

The three balances

All three are integers in minor units, in the account's currency.

{
  "account_id": "acc_01J9QK5N7C",
  "currency": "USD",
  "normal_balance": "credit",
  "posted": 1250000,
  "pending": -300000,
  "available": 950000,
  "as_of": "2026-09-12T10:31:07Z"
}

In that example the wallet holds $12,500.00 of posted funds. A pending payout of $3,000.00 is reserved against it, so $9,500.00 is available to spend.

How available is calculated

An outflow is any entry that decreases the account's normal balance. For a credit-normal wallet, debits are outflows. For a debit-normal cash account, credits are outflows.

available = posted - sum(pending outflows)

Pending inflows do not raise the available balance. Funds you expect to receive cannot be spent until the transaction posts. This protects you from paying out money that later fails to arrive, such as an incoming ACH debit that is returned.

Balance checks at posting time

When you create a transaction, Ledgerline checks the resulting available balance of every account with allow_overdraft set to false. If any would drop below zero, the request fails with insufficient_funds and nothing is written. The check and the write happen atomically, so two concurrent payouts cannot both spend the same funds.

If you need to let an account go negative, for example a settlement account that runs ahead of the bank, create it with allow_overdraft=true.

Reading balances

curl https://api.ledgerline.dev/v1/accounts/acc_01J9QK5N7C/balances \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY"

To read a balance at a past moment, pass as_of:

curl "https://api.ledgerline.dev/v1/accounts/acc_01J9QK5N7C/balances?as_of=2026-08-31T23:59:59Z" \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY"

Historical reads are served from the daily balance snapshots taken at 00:00 UTC, plus the entries since. Snapshots are kept for seven years. See Data residency and retention.

For many accounts at once, GET /v1/ledgers/{id}/balances returns every balance in a ledger, paginated with limit up to 100.

Balances across currencies

Each account has one currency, so there is no single "total" across currencies. To report a combined position, fetch the balances per currency and convert them yourself, or request an indicative value with a quote. See Multi-currency ledgers.

Why a balance may differ from your bank

The ledger records what Ledgerline knows. A bank statement records what the bank has settled. They differ while payments are in flight: a payout that is submitted has left the ledger's available balance but has not yet reached the bank's books. Reconciliation matches the two and shows what is still outstanding.

Locking and concurrency

Reads never block writes. Two simultaneous transactions against the same account are applied one after the other in the order Ledgerline receives them. If you need to guarantee that a decision was based on a particular balance, post a pending transaction first and check that it succeeds: the hold is the lock.

Events

There is no event for every balance change. Subscribe to transaction.posted and payout.paid instead, and read the balance when you need it.