Update a bill schedule
const url = 'https://api.tovarifinancial.com/bills/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0';const options = { method: 'PUT', 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","isActive":true,"nextPaymentDate":"example","amountMinCents":1,"amountMaxCents":1,"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 PUT \ --url https://api.tovarifinancial.com/bills/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \ --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", "isActive": true, "nextPaymentDate": "example", "amountMinCents": 1, "amountMaxCents": 1, "destinationAccountId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "autoEnterMode": "automatic" }'Every field is optional and is merged over the stored row; the EFFECTIVE value of a field is body.field ?? stored.field.
CONVERTING BETWEEN ONE-TIME AND RECURRING is supported in both directions: an edit whose effective frequency crosses the once boundary is normalized server-side rather than refused. The response body is post-conversion and authoritative — re-seed the client from it rather than re-deriving the schedule.
ANCHOR PRECEDENCE on one-time -> recurring: an anchor key PRESENT in the body always wins. An anchor still absent after the merge is DERIVED from the effective start date — monthly/quarterly take its day of month (29/30/31 is kept unclamped; the generator clamps to each month’s real last day), weekly takes its day of week, annually takes its 0-based month plus day of month, biweekly needs none (it anchors on startDate), and twice-monthly derives NOTHING — supply dayOfMonth and a differing day2 or the usual per-field 400 applies.
DATES ON A CONVERSION are server-owned, so startDate is accepted but constrained per arm: freely editable when converting an UNSETTLED one-time item to recurring (it becomes the first occurrence, and nextPaymentDate is rewritten to it); must equal the stored value when converting a SETTLED one-time item to recurring (which preserves the start date and the settle cursor and touches no posted payment) — otherwise 400 fieldErrors.startDate; and must equal the stored value when converting recurring -> one-time, where the surviving occurrence is the PRE-EDIT schedule’s next due date and the response startDate is that survivor. Recurring -> one-time also permanently clears the end condition (endType/endCount/endDate become never/null/null), all four anchors, and every “marked scheduled” declaration on the bill; editing the item back does not restore them. A recurring schedule with no occurrence left at or after its cursor converts to an already-settled one-time item.
FIRST PAYMENT ON A RECURRING BILL (KAN-963): startDate is compared by value. Once the bill’s scheduleStarted is true (an occurrence entered or skipped), a different value is refused with 400 fieldErrors.startDate. While it is false, a changed startDate or a changed cadence shape re-seeds the next payment to the new start date, unless the same request sends nextPaymentDate.
nextPaymentDate is evaluated against the EFFECTIVE frequency: it is refused outright whenever that frequency is once (edit startDate instead), and, when converting a SETTLED one-time item to recurring, refused when it would move the cursor before the occurrence that has already been entered.
Replaying X-Idempotency-Key with the identical body returns the recorded response and writes nothing; the same key with any changed field is 409 IDEMPOTENCY_CONFLICT.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Bill id
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
Integer minor units (cents)
May cross the one-time/recurring boundary in either direction; the conversion is normalized server-side. See the operation description for anchor precedence and the per-arm startDate rules.
Calendar date, ‘YYYY-MM-DD’. Compared by VALUE — resending the stored date is never an edit. On a recurring bill whose scheduleStarted is true, a different value is refused (400, fieldErrors.startDate). On a recurring bill whose schedule has NOT started, a new value (or a cadence-shape change) re-seeds the next payment to the new start date unless the same request sends nextPaymentDate. On a conversion it must equal the stored start date except when converting an UNSETTLED one-time item to recurring.
Calendar date, ‘YYYY-MM-DD’
Calendar date, ‘YYYY-MM-DD’. Refused when the effective frequency is once, and, when converting a SETTLED one-time item to recurring, refused when it would move the settle cursor before the already-entered occurrence.
Integer minor units (cents)
Integer minor units (cents)
Optional transfer counterparty account. PRESENCE-based, not falsiness-based: omit the key and the stored destination is left unchanged; send an explicit null to clear it; send a uuid to set it. Must resolve inside the caller’s own org and differ from the bill’s 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.
KAN-3748. The per-bill Auto-enter setting. PRESENCE-based: omit the key and the stored setting is left unchanged; a body carrying only this key is a valid edit. Any other value (null included — the column is NOT NULL) is a 400 naming autoEnterMode.
Responses
Section titled “Responses”Updated 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"}Resource not found or not owned by the caller org
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}Conflict. errorCode is IDEMPOTENCY_CONFLICT when an X-Idempotency-Key was replayed with a different request payload; where the operation instead detects a resource-state conflict it carries that endpoint’s own errorCode (a duplicate name, an import that is no longer committable, an account already linked to a bank connection).
object
Machine-readable error code (AUTH_ERROR_CODES).
Optional field-level validation errors, keyed by field name.
object
Example
{ "errorCode": "INVALID_EMAIL_FORMAT"}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"}