Create a bill schedule
const url = 'https://api.tovarifinancial.com/bills';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"accountId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","amountCents":1,"direction":"expense","frequency":"once","payeeId":"example","payeeName":"example","memo":"example","budgetCategoryId":"example","dayOfMonth":1,"dayOfWeek":1,"day2":1,"annualMonth":1,"startDate":"example","endType":"never","endCount":1,"endDate":"example","sourceStreamId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","destinationAccountId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","autoEnterMode":"automatic"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api.tovarifinancial.com/bills \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "accountId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "amountCents": 1, "direction": "expense", "frequency": "once", "payeeId": "example", "payeeName": "example", "memo": "example", "budgetCategoryId": "example", "dayOfMonth": 1, "dayOfWeek": 1, "day2": 1, "annualMonth": 1, "startDate": "example", "endType": "never", "endCount": 1, "endDate": "example", "sourceStreamId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "destinationAccountId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "autoEnterMode": "automatic" }'Idempotency: a redelivered X-Idempotency-Key returns the first-persisted resource with 200 — a drifted payload is never applied and never 409s. This path reconciles a replay against a unique index on the stored key rather than the shared idempotency store, so IDEMPOTENCY_CONFLICT is not reachable here (KAN-1416).
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Header Parameters
Section titled “Header Parameters”Optional idempotency key for safe write retries. Every operation that declares this header reads it. Three cases, told apart per operation: (1) where the operation also documents a 409 whose codes include IDEMPOTENCY_CONFLICT, replaying this key with a different payload returns 409 IDEMPOTENCY_CONFLICT and replaying it with the same payload returns the original response; (2) where it documents no 409, a replay is reconciled optimistically against a unique key column and answers the original 200; (3) where it documents a 409 whose codes do NOT include IDEMPOTENCY_CONFLICT, a conflict on this key is impossible — a replay answers a 200, and that 409 is a resource-state conflict described by the operation’s own 409 schema.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Positive magnitude
Calendar date, ‘YYYY-MM-DD’
Calendar date, ‘YYYY-MM-DD’
Recurring suggestion this bill was created from; stamps it converted. Ignored if unresolvable.
Optional transfer counterparty account. Must resolve inside the caller’s own org and must differ from accountId; a malformed, foreign, unknown or self-referencing id all answer with the same destinationAccountId validation error, never a 404. A closed account is accepted. Omit or send null for none.
KAN-3748. The per-bill Auto-enter setting. Omit for the default, automatic. Any other value (null included) is a 400 naming autoEnterMode.
Responses
Section titled “Responses”Created bill
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.
Example
{ "data": { "bill": { "direction": "expense", "frequency": "once", "endType": "never", "occurrenceStatus": "upcoming", "autoEnterMode": "automatic", "outOfBandMatch": { "status": "cleared", "reason": "amount_differs" }, "effectiveToleranceCents": { "source": "manual" } } }}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"}