MEmercurytechnologies
Books

Retrieve a balance sheet

Changed on

Returns the balance sheets for every period (daily, monthly, quarterly, or yearly) in a date range, one column per period. Each column reports balances as of its last day. The response has a list of columns, each with a label, startDate, endDate, and isPartial flag; a tree of rows; and retainedEarnings. Each row has a name, a rowKind, amounts (the row's own balance for each column, excluding its children), totalAmounts (the row's balance for each column, including all of its children), and nested children; the amount lists are ordered to match the columns. Column labels are YYYY-MM-DD for daily, YYYY-MM for monthly, YYYY-Qn (such as 2024-Q1) for quarterly, and YYYY for yearly columns. The rowKind is ledger for a single ledger, i.e. a general ledger (GL) account; summary for a heading that groups ledgers by type or subtype; or computed for a calculated metric. retainedEarnings has, for each column, the system-calculated retained earnings and current year earnings that are added to the Retained Earnings and Current Year Earnings ledger rows. The requested dates are widened to the boundaries of the periods containing them, so a monthly report ending mid-month reports balances as of the end of that month. Each column's startDate and endDate are clamped to the Books entries window (the entries start date through today, in UTC) and describe the days on which posted entries can exist, but journal entries dated in the future can still appear in the column containing today. endDate defaults to today (UTC), or the latest date the span limit allows for startDate, whichever is earlier, but never before startDate, startDate defaults to endDate, and period defaults to daily, so a request without dates returns today's balance sheet as a single column. includeEmpty defaults to false, and includeOnlyClosed defaults to false. Daily reports can span at most 1 year and all other reports at most 5 years; longer ranges fail with the reportDateRangeTooLarge error. To look up the ledgers referenced by ledgerId in the rows, use the list ledgers endpoint (getBooksLedgers).

get/books/reports/balance-sheet

Request

Query parameters

booksIdstring uuid

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

startDatestring date

The report covers the period containing this day and every later period. Defaults to endDate.

endDatestring date

The report covers the period containing this day and every earlier period. Must be on or after startDate. Defaults to today (UTC), or the latest date the span limit allows for startDate, whichever is earlier, but never before startDate.

period'daily' | 'monthly' | 'quarterly' | 'yearly'

The length of time each column covers. Daily reports can span at most 1 year; other periods at most 5 years. Defaults to daily.

includeEmptyboolean

Whether to include ledgers with no balance. Defaults to false.

includeOnlyClosedboolean

Whether to include only activity dated before the latest close. Defaults to false.

Response

Example response

{
  "columns": [
    {
      "endDate": "2016-07-22",
      "startDate": "2016-07-22"
    }
  ],
  "rows": [
    {
      "ledgerId": "7JRNsKwy2Lw66caxVU7WGC",
      "parentId": "7JRNsKwy2Lw66caxVU7WGC"
    }
  ]
}

Changes