Cash flow: inflow / outflow decomposition + projected balance line
const url = 'https://api.tovarifinancial.com/reports/cash-flow?preset=this_month&start=2026-07&end=2026-07&projectionBasis=cash-flow';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://api.tovarifinancial.com/reports/cash-flow?preset=this_month&start=2026-07&end=2026-07&projectionBasis=cash-flow' \ --header 'Authorization: Bearer <token>'The ONE forward-looking report (KAN-678): it alone resolves through selectReportMode(..., { allowFuture: true }), so it alone accepts the next_* presets and a custom range reaching up to 12 months past the current month (an out-of-horizon end is a 400 here, not clamped). Defaults to last_6_months. Inflow and outflow split by SIGN and exclude transfer legs; the actual balance line is a daily reconstruction that deliberately does NOT exclude them, so it foots to the account balance. A projected line is added only when the period reaches the current month. NO budgetOnly — the handler does not read it. ACCOUNT SCOPE: unlike every sibling report, omitting accountIds here does NOT mean all accounts — it means the Safe-to-Spend pool, resolved server-side and applied to all six reads (both KPIs, both top-8 lists, the balance reconstruction and the bills projection) so the actual and projected halves of the chart always range over one account set. An explicit accountIds overrides that verbatim. The applied scope is echoed as accountScope + scopedAccountCount.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Range preset (mutually exclusive with start/end). Includes the forward-looking next_* values, which every other report rejects as unknown.
Month, ‘YYYY-MM’
Example
2026-07Range start month ‘YYYY-MM’
Month, ‘YYYY-MM’
Example
2026-07Range end month ‘YYYY-MM’. May reach at most 12 months past the current month.
Comma-separated account UUIDs to scope the report to. Honoured VERBATIM when present — the explicit list overrides the default scope entirely and is never intersected with it, so naming an account that is excluded from Safe to Spend returns that account’s figures. OMITTING it (or sending an empty value) does NOT mean all accounts on this operation: the server resolves the Safe-to-Spend pool (active accounts with include_in_safe_to_spend = TRUE, possibly none) and every figure in the response ranges over exactly that set. Read accountScope / scopedAccountCount on the response to see which scope was actually applied. A malformed value is rejected with 400 — it is never dropped to an unfiltered report.
KAN-3293, widened by KAN-3762. cash-flow (the default, also when omitted or empty) and ledger are both accepted and draw the SAME projected line and projected KPIs: the ONE projection engine — the walk GET /bills/scheduled uses for its Balance column, over the active accounts the response counts in scopedAccountCount, seeded from the actual line’s today value — so cash-flow is a no-op alias kept for installed builds and cached query keys. Every bill occurrence counts exactly once: overdue and due-today unpaid occurrences step on today + 1, an occurrence already in the register steps zero, a skipped one zero. The ledger basis NO LONGER requires accountIds (absent, the Safe-to-Spend pool resolves exactly as on the default); an EXPLICIT accountIds list on the ledger basis may name at most 10 accounts (400 above that), and the default basis keeps no cap. A matcher failure is a 500 (fail-closed). Any other value is a 400. The response shape is the same on both bases, and a fully-past period runs no projection read.
Responses
Section titled “Responses”Cash-flow report
object
object
The EFFECTIVE account scope every figure in this response was computed over — emitted on every 200, including an empty pool. ‘safe_to_spend’: no accountIds were sent and the server resolved the Safe-to-Spend pool (active accounts with include_in_safe_to_spend = TRUE). ‘explicit’: the caller’s accountIds were honoured verbatim. Clients must render the scope from this value rather than re-deriving it from what they think they sent — a dropped parameter is otherwise undetectable.
How many ACTIVE accounts the reads actually ranged over, on both paths. Not the number of ids requested: a request naming a closed or foreign account reports the smaller, honest number. 0 is legitimate on BOTH paths — with accountScope “safe_to_spend” it means no spendable accounts are configured (a zeroed 200, never an error); with “explicit” it means the requested filter matched no active account. No account id array is ever echoed.
object
KAN-721. The part of kpis.outflowsCents (integer cents, a non-negative magnitude) that went to a transfer-kind category outside the spend universe — every kind=transfer category except the credit-card-payment one (xfer-cc-payment), which outflows[] counts as spend — on rows not linked into a transfer pair: money moved to accounts the household does not track. Server-computed inside the outflow KPI statement, so 0 <= it <= outflowsCents. It explains only the TRANSFER part of the gap between outflowsCents and the sum of outflows[]: the top-8 truncation and negative income/adjustment-kind rows remain unexplained, so clients render it as received and never derive it from the list. Emitted on every 200 by this server; optional in the client schema so older payloads still parse. 0 means nothing to disclose.
Example
{ "data": { "accountScope": "safe_to_spend" }}Validation failed — see errorCode / fieldErrors
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Missing, invalid, or expired bearer token
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Authenticated, but the tenant gate refuses the request until the caller resolves a precondition. errorCode is one of EMAIL_NOT_VERIFIED, POLICY_ACCEPTANCE_REQUIRED, or SUBSCRIPTION_REQUIRED, evaluated in exactly that order (contract term CCR-1: email verification first, then policy acceptance, then subscription — so a subscriber who has merely not re-accepted the current policies always sees POLICY_ACCEPTANCE_REQUIRED). A POLICY_ACCEPTANCE_REQUIRED body additionally carries details.outstanding (the policy versions still to accept) and details.firstAcceptance. The SUBSCRIPTION_REQUIRED arm is INERT unless the server-side BILLING_ENABLED flag is exactly the string true; while it is off, only the first two codes are reachable. Not retryable as sent — resolve the named condition, then resend.
object
Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.
object
Active policy versions the user has not yet accepted.
object
True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.
Example
{ "errorCode": "EMAIL_NOT_VERIFIED"}Internal error (no internal detail leaked)
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Service temporarily unavailable — errorCode is SERVICE_UNAVAILABLE. A TRANSIENT, RETRYABLE condition rather than a defect in the request: a query that exceeded its time budget, a lost or refused database connection, a saturated connection pool, or an outage at an upstream provider the request depends on (the authentication provider, or the bank data provider on a bank-connection operation). The identical request may succeed on retry — back off briefly and, on a write, resend the same X-Idempotency-Key where the operation accepts one.
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}