MEmercurytechnologies
Books

Retrieve a profit and loss statement

Changed on

Returns a profit and loss statement (P&L), i.e. an income statement, for a date range, either as a single column covering the whole range or broken down by period (daily, monthly, quarterly, or yearly). The response has a list of columns, each with a label, startDate, endDate, and isPartial flag, and a tree of rows. Each row has a name, a rowKind, amounts (the row's own amount for each column, excluding its children), totalAmounts (the row's amount 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, and YYYY-MM-DD - YYYY-MM-DD for a single column covering the whole range. The response has no total across columns: the Total column on the Books Reports page is computed client-side, and totalAmounts still has one amount per column. To total a range, sum a row's per-column amounts, or omit period to get a single column covering the whole range. 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 such as gross profit or net profit. Column amounts are full-period totals: the requested dates are widened to the boundaries of the periods containing them, so a monthly report starting mid-month still covers the whole first 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. startDate defaults to the entries start date (or the earliest date the span limit allows for the end date, whichever is later, but never after the end date), endDate defaults to today (UTC), or the latest date the span limit allows for startDate, whichever is earlier, but never before startDate, omitting period returns a single column covering the whole range, 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/profit-and-loss

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 the Books entries start date, or the earliest date the span limit allows for the end date, whichever is later, but never after the end date.

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 a single column covering the whole range, which can also span at most 5 years.

includeEmptyboolean

Whether to include ledgers with no activity. 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