List bill schedules
const url = 'https://api.tovarifinancial.com/bills';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 \ --header 'Authorization: Bearer <token>'The WHOLE tenant schedule set — complete and unpaginated; the handler reads no account filter, so a client scopes the list itself (each Bill carries accountId, isActive and nextDueDate). The summary block is org-wide and is never moved by includeSettled.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Set to ‘1’ to also return SETTLED bills (a one-time bill already paid, a schedule whose cursor has run past its end). Any other value, or absence, hides them. The summary is unaffected.
Responses
Section titled “Responses”Bills + summary
object
object
object
Integer minor units (cents)
Calendar date, ‘YYYY-MM-DD’
Calendar date, ‘YYYY-MM-DD’
Server-computed (KAN-963): true once an occurrence of this schedule has been entered or skipped — any payment-history row, or the settle cursor past the first occurrence. True means First Payment is locked: a recurring bill then refuses a changed startDate. Emitted on every bill row; never recompute it on the client.
Calendar date, ‘YYYY-MM-DD’
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
Presentation metadata for the occurrence at nextDueDate, stamped on EVERY bill row. Meaningful only alongside a non-null nextDueDate — an exhausted, settled or paused schedule has no occurrence to be pending or late and carries the neutral upcoming, as does a next occurrence that is skipped (KAN-3365 — never rendered late).
Integer minor units (cents)
Integer minor units (cents)
Transfer counterparty account (the source stays accountId). Null when the bill declares none, in which case Safe to Spend keeps skipping a pooled transfer bill. Emitted on every bill row.
KAN-3748. The per-bill Auto-enter setting: automatic (the default) — a payment the server finds for this bill is entered unattended, with a bills.auto_entered notification; ask_first — the payment is offered for the household to confirm and never entered unattended. Emitted on every bill row.
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
ScheduledMark ? its scheduledPaymentDate : this row’s own nextDueDate. NULLABLE here, unlike the per-occurrence surfaces: it mirrors nextDueDate, and an exhausted, settled or paused schedule has no occurrence and therefore no effective date for one.
SIGNED (income +, expense −), server-computed as declaration → forecast → schedule. 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 the nextDueDate occurrence (a Cash Flow “this occurrence only” edit), or null (KAN-2926/KAN-3364). Null whenever nextDueDate is null. Outranked by scheduledMark when both are present; already folded into effectiveDueDate.
The FORECAST-ONLY amount override on the nextDueDate occurrence, as the POSITIVE MAGNITUDE it is stored as, or null (KAN-2926/KAN-3364). The signed figure is effectiveAmountCents; amountCents stays the series amount. Outranked by scheduledMark when both are present.
“Do not count this one” on the nextDueDate occurrence (KAN-2913/KAN-3364). False whenever nextDueDate is null. Presentation only on this surface — it moves no figure in summary and is not POST /bills/{id}/skip: no cursor moves.
KAN-2868 — the TIER-2 “Payment found” offer the matching engine makes for the nextDueDate occurrence: the same object GET /bills/scheduled emits on that occurrence. Explicit null when nextDueDate is null, the bill has no account, nothing is offered, or the match scan failed. Presentation only: it does NOT widen occurrenceStatus (payment_pending still means a pending match), settles nothing and moves no figure in summary. Older servers omit the key.
object
SIGNED ledger cents, passed through exactly as stored.
Calendar date, ‘YYYY-MM-DD’
The register’s display text — transactions.description, never bank_description.
The bank row’s own status, so a confirmed Enter claims the row with the value it was offered under.
WHICH ROUTE offered the row. Always emitted by the server, but deliberately NOT required: a client that does not recognise the value must keep rendering its existing copy rather than discarding the match.
The amount band learned from this bill’s own in-band payment history, or null when there is not enough history to learn one. Display only.
object
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
The amount band this bill is presented as accepting, and WHICH input produced it — a manual min/max override, the learned range, or the default. Display only.
object
Integer minor units (cents)
Integer minor units (cents)
KAN-3748, GET /bills only. The bill’s latest settlement when the server entered it UNATTENDED (an engine route) AND POST /transactions/{id}/unsettle can still reverse it, else null — the “Auto-entered Oct 8 · Undo” activity entry.
object
The bank row Undo releases (POST /transactions/{id}/unsettle).
Calendar date, ‘YYYY-MM-DD’
The bank row’s posted date — the date the notification names.
POSITIVE magnitude paid.
object
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Example
{ "data": { "bills": [ { "direction": "expense", "frequency": "once", "endType": "never", "occurrenceStatus": "upcoming", "autoEnterMode": "automatic", "outOfBandMatch": { "status": "cleared", "reason": "amount_differs" }, "effectiveToleranceCents": { "source": "manual" } } ] }}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"}