Ledgers and accounts

Updated 3 September 20263 min read

On this page

A ledger is a book of record. It contains accounts, and accounts accumulate entries. Everything else in Ledgerline, from payouts to statements, is built on top of that structure.

Ledgers

A ledger groups accounts that belong together. Common choices are one ledger per product line, per legal entity or per environment of a marketplace. Accounts in different ledgers cannot appear in the same transaction, so draw the boundary where you do not need to move money atomically.

{
  "id": "led_01J9QK3ZV8",
  "name": "Customer funds",
  "description": "Funds held on behalf of customers",
  "created_at": "2026-09-03T08:14:22Z",
  "metadata": { "product": "wallets" }
}

The number of ledgers you can create depends on your plan: 3 on Starter, 25 on Growth and 250 on Scale. See Limits and quotas.

Accounts

An account holds a balance in one currency. It belongs to exactly one ledger.

Field	Meaning
`id`	Account id, prefixed `acc_`.
`ledger_id`	The ledger the account belongs to. Fixed at creation.
`name`	A human-readable label.
`currency`	ISO 4217 code such as `USD`. Fixed at creation.
`normal_balance`	`debit` or `credit`. Fixed at creation.
`allow_overdraft`	Whether the available balance may go below zero. Defaults to `false`.
`status`	`active`, `frozen` or `closed`.
`metadata`	Up to 50 key-value pairs of your own data.

Normal balance

Double-entry bookkeeping needs every account to declare which side increases it.

A debit-normal account grows when you debit it. Assets and expenses work this way: operating cash, receivables.
A credit-normal account grows when you credit it. Liabilities, equity and revenue work this way: a customer wallet is a liability, because you owe that money to the customer.

Choose the normal balance by asking "whose money is this?". If it is yours, it is probably debit-normal. If you are holding it for someone else, it is credit-normal.

Tip

Model each customer's wallet as its own credit-normal account and keep one debit-normal account for the cash you hold at the bank. The sum of all wallets should equal the cash, which is exactly what reconciliation checks.

Creating an account

curl https://api.ledgerline.dev/v1/accounts \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Idempotency-Key: 8b7a5e2c-2f6e-4a39-b8a0-45d1e7f3c9a4" \
  -d ledger_id=led_01J9QK3ZV8 \
  -d name="Wallet: Acme Freight" \
  -d currency=USD \
  -d normal_balance=credit \
  -d "metadata[customer_ref]=cus_4821"

Account creation is cheap. Plans allow 10,000 accounts per ledger on Starter, 250,000 on Growth and 5,000,000 on Scale, so one account per customer is a normal pattern.

Freezing and closing

Freeze an account to stop new entries while you investigate: POST /v1/accounts/{id}/freeze. Posting to a frozen account fails with account_frozen. Unfreeze with POST /v1/accounts/{id}/unfreeze.
Close an account once its balance is zero: POST /v1/accounts/{id}/close. Closing a non-zero account fails. Closed accounts and their entries stay readable for seven years. See Data residency and retention.

Virtual accounts

A virtual account is a real routing and account number that Ledgerline maps to one of your ledger accounts. Incoming ACH, wire and instant payments addressed to it are posted to the account automatically. Create one with POST /v1/virtual_accounts and attach it to the account that should receive the funds. Each customer wallet can have its own, which makes incoming payments identify themselves.

Reading accounts

GET /v1/accounts lists accounts with cursor pagination. Filter by ledger_id, currency, status or metadata[key]. Balances are read from GET /v1/accounts/{id}/balances, described in Account balances.

For the rules that govern what you can post to an account, continue to Transactions and entries.