Books

Retrieve ledger balances over a date range

Changed on

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).

get/books/ledger-balances

Request

Query parameters

ledgerIdsstring[] required

Ledger IDs to report on. Send the parameter repeated (ledgerIds=a&ledgerIds=b) or as one comma-separated value (ledgerIds=a,b). At least one and at most 100 distinct IDs.

[
  "7JRNsKwy2Lw66caxVU7WGC"
]
startDatestring date required

First day of the range (inclusive), as YYYY-MM-DD. Opening balances are as of the end of the previous day.

endDatestring date required

Last day of the range (inclusive), as YYYY-MM-DD. Must not be before startDate. Closing balances are as of the end of this day.

booksIdstring uuid

The Books instance to act on. Must be the token organization's own instance, which it defaults to.

Response

Example response

{
  "ledgerBalances": [
    {
      "ledgerId": "7JRNsKwy2Lw66caxVU7WGC"
    }
  ]
}

Changes