---
title: "Retrieve ledger balances over a date range"
method: GET
path: "/books/ledger-balances"
tags: ["Books"]
---

# Retrieve ledger balances over a date range

`GET /books/ledger-balances`

## Request

- Base URL: `https://api.mercury.com/api/v1`
- URL: `https://api.mercury.com/api/v1/books/ledger-balances`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mercurytechnologies/apis/mercury-api/docs/books/ledger-balances/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the opening balance, closing balance, and net activity of one or more ledgers (general ledger (GL) accounts) over a date range, along with each ledger's debit/credit nature. Use this for questions such as "what was the balance of this account at the end of March?" or "how much moved through these accounts last quarter?". Each entry has `ledgerId`, `name`, `type`, `subType`, `specialType` (set only for system ledgers such as retained earnings), `openingBalance` (balance at the end of the day before `startDate`), `closingBalance` (balance at the end of `endDate`), `netActivity` (the change between them), and `debitCredit`. Amounts are positive when they increase the ledger on its natural side: a `debit` ledger (such as an asset or expense) grows with debits and a `credit` ledger (such as a liability, equity, or revenue) grows with credits. They are not normalized to a single debit-positive sign. Balances cover only each ledger's own line entries and do not roll up child ledgers; to total a parent ledger, request its children too. Opening-balance entries count, and the Retained Earnings and Current Year Earnings system ledgers also include the calculated earnings, so they match the balance sheet. A ledger with no activity returns zeros. Entries come back in request order, one per distinct ID. At most 100 distinct ledger IDs per request; every ID must belong to the Books instance. To discover ledger IDs, use the list ledgers endpoint (getBooksLedgers).

## Query parameters

- `ledgerIds` string[], required
- `startDate` string, date, required
- `endDate` string, date, required
- `booksId` string, uuid: The Books instance to act on. Must be the token organization's own instance, which it defaults to.

## Response `200`

- GetBooksAPILedgerBalancesResponse: Response containing the balances of the requested ledgers.
  - `ledgerBalances` BooksAPILedgerBalance[], required: One entry per distinct requested ledger, in the order the ledgers were requested.
    - `closingBalance` number, double, required: The balance at the end of `endDate`.
    - `debitCredit` 'debit' | 'credit', required: Whether the ledger has a natural debit or credit balance, which is the side that positive amounts increase.
    - `ledgerId` string, base58 (max length 22), required: The ledger these balances belong to.
    - `name` string, required: The ledger's display name.
    - `netActivity` number, double, required: The net change over the range: all of the ledger's line entries from `startDate` through `endDate`.
    - `openingBalance` number, double, required: The balance at the end of the day before `startDate`.
    - `specialType` 'uncatInflow' | 'uncatOutflow' | 'accountTransfers' | 'openingBalances' | 'accountsReceivable' | 'accountsPayable' | 'wagesExpense' | 'bonusExpense' | 'commissionsExpense' | 'contractorExpense' | 'employeeReimbursements' | 'severanceExpense' | 'payrollTaxExpense' | 'employerBenefitsExpense' | 'healthInsuranceExpense' | 'wagesPayable' | 'payrollTaxPayable' | 'employeeBenefitLiabilities' | 'payrollLiabilities' | 'payrollAdjustmentsClearing' | 'retainedEarnings' | 'currentYearEarnings' | 'benefitsExpense' | 'donationsExpense' | 'benefitsPayable' | 'payrollTaxAccruals' | 'stockExerciseClearing' | 'payrollClearing', nullable: The system function of a required ledger, such as `retained_earnings`, if it has one.
    - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings', required: The ledger's more specific accounting classification.
    - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense', required: The ledger's top-level accounting classification.

## Other responses

- `400`: Invalid `booksId` or `endDate` or `startDate` or `ledgerIds`

## Changes

- **2026-11-03** `95c77a617769`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/ledger-balances/get.md)

---

[API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) - [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mercurytechnologies/apis/mercury-api/revisions/95c77a617769?raw)