Cash-forecast

Cash forecast: today's cash and what comes in and goes out in each of the next 13 weeks, from open invoices and bills at each party's payment habit, payments not posted yet and what recurring invoices, subscriptions and recurring journals will make; with its lowest point and what changed since the forecast of an earlier week. Nothing here posts.

Operation	Summary	Scope	Idempotency-Key
`GET /v1/entities/{entity}/cash-forecast`	Forecast cash for 13 weeks	`read`

`GET /v1/entities/{entity}/cash-forecast`

Forecast cash for 13 weeks

Today's cash and what comes in and goes out in each of the 13 weeks from this week's Monday: open invoices and bills at the day each customer usually pays (and each vendor is usually paid) over the last 12 months, payments recorded but not posted yet, the invoices recurring invoices and subscriptions will make, and recurring journals on a cash account. With the lowest cash at a week's end, every line behind the weeks, and what changed since the forecast kept in an earlier week (kept once a week by the scheduled jobs). Nothing is posted.


Required scope	`read` (`admin` implies every scope)
Operation id	`get_cash_forecast_v1_entities__entity__cash_forecast_get`

Parameters

In	Name	Type	Required	Description
path	`entity`	string	yes	Entity code, e.g. `CH01` (`GET /v1/entities`).
query	`as_of`	string (date) or null		Make it as on this day; default the company's today.

Example request

curl "$ERP_URL/v1/entities/CH01/cash-forecast" \
  -H "Authorization: Bearer $ERP_KEY"

Responses

Status	Meaning	Body
200	OK	`CashForecastOut`
401	Missing or invalid API key (`unauthorized`).	`ErrorEnvelope`
403	The caller lacks the required scope (`missing_right`, with `scope`), the key belongs to no person where a person is needed (`forbidden`), or the approval policy denies the action (`policy_denied`, with `action` and `rule_id`).	`ErrorEnvelope`
404	The resource does not exist, or belongs to another organization (`not_found`).	`ErrorEnvelope`
422	Validation failed: the error envelope (`validation_failed`). For a malformed body or parameter its message is in sentences ("Line 2: the quantity must be above zero") and `fields` lists each error with pydantic's `loc`, `type` and `msg` beside its sentence (`message`) and its parts, to word it in another language: `items` (`name` and `number` from 1: line 2), `field` (its name as sent) and the `rule` it breaks with its `limit`, `count` and `choices` (none for a validator's own sentence); FastAPI's own `detail` list stays beside the envelope.	`HTTPValidationError`

Example response (shape)

{
  "entity": "string",
  "currency": "string",
  "as_of": "2026-09-21",
  "opening": "string",
  "weeks": [
    {
      "number": 1,
      "start": "2026-09-21",
      "end": "2026-09-21",
      "inflow": "string",
      "outflow": "string",
      "net": "string",
      "closing": "string",
      "by_source": {}
    }
  ],
  "lowest": {
    "week": 1,
    "date": "2026-09-21",
    "amount": "string",
    "below_zero": true
  },
  "lines": [
    {
      "key": "string",
      "source": "payable",
      "reference": "string",
      "party_code": "string",
      "party_name": "string",
      "date": "2026-09-21",
      "due_date": "2026-09-21",
      "week": 1,
      "basis": "company_habit",
      "habit_days": 1,
      "overdue": true,
      "currency": "string",
      "amount": "string",
      "functional": "string",
      "link": "string",
      "posted": true
    }
  ],
  "later": "string",
  "habits": 1,
  "changes": {
    "since": "2026-09-21",
    "opening_before": "string",
    "opening_after": "string",
    "lowest_before": {
      "week": null,
      "date": null,
      "amount": null,
      "below_zero": null
    },
    "totals": {},
    "items": [
      null
    ],
    "more": 1
  }
}

Schemas

`CashForecastOut`

Field	Type	Required	Description
`entity`	string	yes	Code of the company.
`currency`	string	yes	Its functional currency: every total is in it.
`as_of`	string (date)	yes	The day it was made for (the company's today).
`opening`	string	yes	The cash the books hold on that day (cash accounts).
`weeks`	array of `ForecastWeek`	yes	Thirteen weeks from this week's Monday.
`lowest`	`LowestPoint`	yes	The least cash at a week's end.
`lines`	array of `ForecastLine`	yes	Every amount behind the weeks, by day.
`later`	string	yes	What open invoices and bills bring or take after the thirteenth week.
`habits`	integer	yes	How many customers and vendors have a payment habit.
`changes`	`ForecastChanges` or null	yes	What changed since the forecast kept in an earlier week; null before one is.

`ForecastChange`

Field	Type	Required	Description
`kind`	`"amount"` \| `"came_into_view"` \| `"moved"` \| `"new"` \| `"settled"`	yes	`settled` (expected before, gone now: paid, collected or cancelled), `new` (not expected before), `moved` (expected in another week now), `amount` (another amount now), `came_into_view` (in the week the horizon moved on to).
`source`	`"payable"` \| `"payment"` \| `"receivable"` \| `"recurring_invoice"` \| `"recurring_journal"` \| `"subscription"`	yes	Where it comes from: `receivable` (an open customer invoice or credit note), `payable` (an open vendor bill or credit note), `payment` (a payment recorded but not posted yet: one waiting for approval, a payment run's), `recurring_invoice` and `subscription` (an invoice they will make), `recurring_journal` (an entry it will post on a cash account).
`reference`	string	yes	The document's number, the template's name.
`party_name`	string or null	yes	The customer's or vendor's name.
`before_date`	string (date) or null	yes	When it was expected before.
`after_date`	string (date) or null	yes	When it is expected now.
`before`	string	yes	What was expected before, in the company's currency.
`after`	string	yes	What is expected now, in the company's currency.
`link`	string or null	yes	The app page of the document or template, if any.

`ForecastChanges`

Field	Type	Required	Description
`since`	string (date)	yes	The day the earlier forecast was kept.
`opening_before`	string	yes	The cash on that day.
`opening_after`	string	yes	The cash today.
`lowest_before`	`LowestPoint`	yes	The lowest point the earlier one showed.
`totals`	map of string	yes	The change each kind made to the cash over the weeks both forecasts cover.
`items`	array of `ForecastChange`	yes	The changes, largest first (at most 25).
`more`	integer	yes	How many smaller changes are not listed.

`ForecastLine`

Field	Type	Required	Description
`key`	string	yes	Stable from one week to the next: what it is and its record.
`source`	`"payable"` \| `"payment"` \| `"receivable"` \| `"recurring_invoice"` \| `"recurring_journal"` \| `"subscription"`	yes	Where it comes from: `receivable` (an open customer invoice or credit note), `payable` (an open vendor bill or credit note), `payment` (a payment recorded but not posted yet: one waiting for approval, a payment run's), `recurring_invoice` and `subscription` (an invoice they will make), `recurring_journal` (an entry it will post on a cash account).
`reference`	string	yes	The document's number, the template's name.
`party_code`	string or null	yes	The customer's or vendor's code.
`party_name`	string or null	yes	The customer's or vendor's name.
`date`	string (date)	yes	The day the cash is expected (today at the earliest).
`due_date`	string (date) or null	yes	The day it falls due, where it has one.
`week`	integer	yes	The week it falls in, 1 (this week) to 13.
`basis`	`"company_habit"` \| `"customer_habit"` \| `"dated"` \| `"due_date"` \| `"vendor_habit"`	yes	How its day was found: `customer_habit` or `vendor_habit` (the due date moved by how late this customer paid, or this vendor was paid, over the last 12 months), `company_habit` (the same for all of the company's customers or vendors, for a party without payments yet), `due_date` (no payments to learn from) or `dated` (a payment's date, an entry's).
`habit_days`	integer or null	yes	Days after the due date this party pays or is paid on average (negative: before); null where the day is a date.
`overdue`	boolean	yes	Its expected day has passed: counted in this week.
`currency`	string	yes	The currency it moves in.
`amount`	string	yes	In `currency`, signed: positive comes in.
`functional`	string	yes	In the company's currency, signed.
`link`	string	yes	Where the app shows it.
`posted`	boolean	yes	Whether it is a posted document; false for a draft or a document or payment waiting for approval, and for what is scheduled.

`ForecastWeek`

Field	Type	Required	Description
`number`	integer	yes	1 (this week, from Monday) to 13.
`start`	string (date)	yes	Its Monday.
`end`	string (date)	yes	Its Sunday.
`inflow`	string	yes	What comes in.
`outflow`	string	yes	What goes out, as a positive amount.
`net`	string	yes	Inflow less outflow.
`closing`	string	yes	The cash at the week's end.
`by_source`	map of string	yes	The net amount of each source.

`LowestPoint`

Field	Type	Required	Description
`week`	integer	yes	The week whose end has the least cash (0: today's cash).
`date`	string (date)	yes	That week's Sunday (today for week 0).
`amount`	string	yes	The cash then.
`below_zero`	boolean	yes	Whether it is below zero.