Dashboard balance projection + upcoming bills
const url = 'https://api.tovarifinancial.com/bills/projection?accountScope=all&forwardMonths=3';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/bills/projection?accountScope=all&forwardMonths=3' \ --header 'Authorization: Bearer <token>'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Narrows the SERIES ONLY (net-worth base, day-net history, account openings, and the bill occurrences that step the projected line). Since KAN-3762 the projected line is the ONE projection engine (the /bills/scheduled ledger walk) over the ACTIVE accounts the scope returns, so under ‘all’ a bill with NO account, or on a DEACTIVATED account, no longer moves any point — it still counts in remainingDueThisMonthCents / overdueDueCents / upcomingBills. Every bill occurrence counts exactly once: overdue and due-today unpaid occurrences step on today + 1, an occurrence already in the register (a pending or cleared bank row, a one-for-one tie, a hand-typed row) steps zero, a skipped one zero, and a matcher failure is a 500 (fail-closed). Absent or empty => ‘all’, which is byte-identical to the unscoped response. ‘checking’ / ‘savings’ / ‘investment’ narrow by account type; ‘safe_to_spend’ narrows to the Safe-to-Spend POOL — the accounts matching is_active = TRUE AND include_in_safe_to_spend = TRUE, the same universe the Safe to Spend headline and the Cash Flow report default to (migration 014’s CHECK keeps investment / credit_card / loan accounts out of it). A pool with no members is a normal 200 carrying includedAccountCount 0, currentNetWorthCents 0 and lowestProjected null — never an error. An unknown value is rejected with 400 and is never coerced to ‘all’. remainingDueThisMonthCents, overdueDueCents and upcomingBills are deliberately NOT scoped under ANY value — they belong to the adjacent Upcoming Bills card, which shares this response.
How many whole months forward the PROJECTED series runs. An integer in [1, 12]; absent or empty => 3, which reproduces the response this endpoint has always returned. The horizon is the LAST DAY of that month, so the window is always month-aligned — there is no start/end date pair and no end alias, because an arbitrary end date would have to be snapped to a month end, which is the silent clamp this parameter exists to avoid. The bound is the same MAX_FUTURE_MONTHS /reports/cash-flow uses. Out of bounds or malformed is a 400 naming the allowed bound — never a clamp, and the message never echoes the value sent. The HISTORY half of the series is fixed at 3 months back and does not move. upcomingBills[], remainingDueThisMonthCents and overdueDueCents deliberately do NOT follow this parameter: the first stays pinned to the default 3-month enumeration and the other two are current-calendar-month figures, because a Balance Projection control must not mutate the adjacent Upcoming Bills card. projectedEndCents and lowestProjected DO follow it — they describe the series.
Responses
Section titled “Responses”Projection
object
object
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
Integer minor units (cents)
object
Integer minor units (cents)
Calendar date, ‘YYYY-MM-DD’
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
The occurrence’s effective date, resolved server-side as declaration → forecast → schedule (KAN-2926): scheduledMark ? its scheduledPaymentDate : forecastDate ?? this row’s own dueDate. dueDate keeps its own meaning and value.
SIGNED (income +, expense −), server-computed as declaration → forecast → schedule (KAN-2926). Equals the schedule’s own signed amount when no override is present. Never re-derive a sign on the client.
The FORECAST-ONLY date override on this occurrence, or null (KAN-2926). ALWAYS emitted. Outranked by scheduledMark when both are present. It moves presentation and the projected step only — never month bucketing, window membership or Safe to Spend.
The FORECAST-ONLY amount override, as the POSITIVE MAGNITUDE it is stored as, or null (KAN-2926). ALWAYS emitted. The signed figure is effectiveAmountCents; never re-sign this on the client. Outranked by scheduledMark when both are present.
Whether the household has marked this occurrence “do not count” (KAN-2926). ALWAYS emitted by this server. A skipped occurrence contributes a ZERO delta to points and is excluded from remainingDueThisMonthCents / overdueDueCents, while keeping its own amountCents and effectiveAmountCents.
KAN-1033 — the server’s ONE render discriminator (the union GET /bills and GET /bills/scheduled emit), resolved through the same precedence: payment_pending when a PENDING bank row covers this occurrence at the unattended trust class, else marked_scheduled / overdue / upcoming from the declaration, the date and the skip. match_ambiguous is never emitted on this list (it renders no chooser). upcoming for an occurrence the cursor already passed. ALWAYS emitted by this server; older servers omit the key. Presentation only.
KAN-1033 — WHY the matching engine says this occurrence is already in the register (the same answer GET /bills/scheduled gives), or null. Read from the shared covered-occurrence loader over the ACCOUNT-COMPLETE pool (never narrowed by a filter), only for an outstanding occurrence due on or before today + 7 days; null past that reach, for an occurrence already paid, and whenever the scan was skipped or failed (a failed scan never fails the response). A non-null value is exactly an occurrence the projected line steps by ZERO as already in the register; remainingDueThisMonthCents and overdueDueCents still count it (ruling R5), and its pool is never narrowed by accountScope, so a Balance Projection chip never changes it. ALWAYS emitted by this server (explicit null when none); older servers omit the key, and a client must tolerate an unknown future member.
The EFFECTIVE scope, echoed on every path so a param-dropping proxy is detectable client-side.
How many accounts the scope matched. Emitted on EVERY path including the default one, and 0 is a legitimate value (an accountScope that matched nothing — e.g. an empty Safe-to-Spend pool) that clients key their empty state on.
The lowest point of the PROJECTED series (ties resolve to the earliest date) — the projection footer figure, computed server-side. NULL when the scope matched no accounts or no point carries a projected value; never a fabricated $0. Since KAN-3762 it is the ONE projection engine’s reading — identical to Bills Cash Flow’s and the register’s for the same accounts and horizon.
object
Integer minor units (cents)
Calendar date, ‘YYYY-MM-DD’
KAN-3762 — the first day on or after today whose projected balance is below zero, or null when the line never crosses zero (and null over an empty roster). Read off the SAME engine line as lowestProjected. Always emitted by this server; absent from older ones.
The EFFECTIVE forward window, echoed on EVERY 200 including the default unqueried path — the only way a caller can tell the window it GOT from the window it asked for (the accountScope echo precedent). throughIso is the last day of the projected series, i.e. the last point in points. On the default path it is exactly { forwardMonths: 3, throughIso: end of the month 3 months ahead }.
object
Calendar date, ‘YYYY-MM-DD’
Example
{ "data": { "upcomingBills": [ { "direction": "expense", "frequency": "once", "occurrenceStatus": "upcoming", "registerReflection": "pending_match" } ], "accountScope": "all" }}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"}