MEmercurytechnologies
Books

Retrieve a cash flow report

Changed on

Returns a cash flow report for a date range, either as a single column covering the whole range or broken down by period (daily, monthly, quarterly, or yearly). For each column, it shows the total starting and ending balances across all cash ledgers, as well as a per-ledger breakdown of starting balance, ending balance, and net cash flow. It is a per-ledger cash flow analysis, not a statement of cash flows grouped into operating, investing, and financing activities. The response has a list of columns, each with a label, startDate, endDate, and isPartial flag; ledgers, a tree of the ledgers that cash moved through; startingBalances and endingBalances, trees of the cash ledgers' balances at the start and end of each column; and startingCashBalances and endingCashBalances, the total debit balance of all cash ledgers at the start and end of each column. Each ledgers entry has a ledgerId, name, netCashFlows (for each column, the sum of the ledger's own cash line entries, excluding its children), totalNetCashFlows (the same sum including all of its children), and nested children. Each startingBalances and endingBalances entry has a ledgerId, name, sortCode, balances (the ledger's own debit balance for each column, excluding its children), totalBalances (the debit balance including all of its children), and nested children. Every per-column list is 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 totalNetCashFlows and totalBalances still have one amount per column. To total a range, sum a ledger's per-column net cash flows, or omit period to get a single column covering the whole range. 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, 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, use the list ledgers endpoint (getBooksLedgers).

get/books/reports/cash-flow

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.

includeOnlyClosedboolean

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

Response

endingCashBalancesDollar[] required

For each column, the total debit balance of all cash ledgers at the end of the column.

startingCashBalancesDollar[] required

For each column, the total debit balance of all cash ledgers at the start of the column.

Example response

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

Changes