--- title: "Retrieve a balance sheet" method: GET path: "/books/reports/balance-sheet" tags: ["Books"] --- # Retrieve a balance sheet `GET /books/reports/balance-sheet` ## Request - Base URL: `https://api.mercury.com/api/v1` - URL: `https://api.mercury.com/api/v1/books/reports/balance-sheet` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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). ## Query parameters - `booksId` string, uuid: The Books instance to act on. Must be the token organization's own instance, which it defaults to. - `startDate` string, date: The report covers the period containing this day and every later period. Defaults to endDate. - `endDate` string, 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. - `includeEmpty` boolean: Whether to include ledgers with no balance. Defaults to false. - `includeOnlyClosed` boolean: Whether to include only activity dated before the latest close. Defaults to false. ## Response `200` - BooksAPIReport: An income statement or balance sheet broken down into columns. - `columns` BooksAPIReportColumn[], required: The report's columns, in chronological order. - `endDate` string, date, nullable: The last day (inclusive) of the column that falls between the Books entries start date and today. Omitted, along with @startDate@, when no day of the column falls in that window. - `isPartial` boolean, required: Whether @startDate@ and @endDate@ cover fewer days than the column's label, because the label extends before the Books entries start date or after today. Always true when @startDate@ and @endDate@ are omitted. - `label` string, required: The column's name: @yyyy@ (yearly), @yyyy-Qn@ (quarterly), @yyyy-MM@ (monthly), @yyyy-MM-dd@ (daily), or @yyyy-MM-dd - yyyy-MM-dd@ when the report is not broken down by period. - `startDate` string, date, nullable: The first day (inclusive) of the column that falls between the Books entries start date and today. Omitted, along with @endDate@, when no day of the column falls in that window. - `retainedEarnings` object, nullable: System-calculated equity amounts. Present on balance sheets; omitted on income statements. - `calculatedCurrentYearEarnings` Dollar[], required: For each column, current-year revenues minus current-year expenses, before journal entries posted to the Current Year Earnings ledger. - `calculatedRetainedEarnings` Dollar[], required: For each column, prior-year revenues minus prior-year expenses, before journal entries posted to the Retained Earnings ledger. - `rows` BooksAPIReportRow[], required: The report's top-level rows. - `amounts` Dollar[], required: The row's own amount for each column, excluding its children. - `children` BooksAPIReportRow[], required: The rows nested under this row. - `debitCredit` 'debit' | 'credit', required: Whether the row's amounts have a natural debit or credit balance. - `ledgerId` string, base58 (max length 22), nullable: The ledger this row represents. Omitted unless @rowKind@ is @ledger@. - `name` string, required: The ledger name, the summary heading, or the name of the calculated metric. - `parentId` string, base58 (max length 22), nullable: The parent ledger of this row's ledger, if it is nested. - `rowKind` 'ledger' | 'summary' | 'computed', required: What the row represents. - `sortCode` string, nullable: The ledger/account number used for chart ordering. Omitted unless @rowKind@ is @ledger@. - `subType` 'currentAssets' | 'nonCurrentAssets' | 'transfersBetweenAccounts' | 'uncategorizedAssets' | 'currentLiabilities' | 'nonCurrentLiabilities' | 'equity' | 'operatingRevenues' | 'otherIncome' | 'costOfGoodsSold' | 'operatingExpenses' | 'otherExpenses' | 'retainedEarnings', nullable: The ledger's more specific accounting classification. Omitted unless @rowKind@ is @ledger@. - `totalAmounts` Dollar[], required: The row's amount for each column, including all of its children. - `type` 'asset' | 'liability' | 'equity' | 'revenue' | 'expense', nullable: The top-level accounting classification of the row's ledger or summary grouping. Omitted on @computed@ rows. ## Other responses - `400`: Invalid `includeOnlyClosed` or `includeEmpty` or `period` or `endDate` or `startDate` or `booksId` ## Changes - **2026-11-03** `95c77a617769`: 1 info - endpoint added [Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/reports/balance-sheet/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)