Skip a scheduled occurrence (advance cursor only)
const url = 'https://api.tovarifinancial.com/bills/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/skip';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"occurrenceDate":"example"}'};
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/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/skip \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "occurrenceDate": "example" }'X-Idempotency-Key is HONORED (KAN-1517), through the shared idempotency store. A redelivery of the same key with the same body replays the recorded 200 envelope byte for byte and advances next_payment_date no further; the same key carrying a different occurrenceDate, or aimed at a different bill, is refused 409 IDEMPOTENCY_CONFLICT rather than applied as a second skip. The key is optional — an unkeyed request behaves exactly as before. An unkeyed retry cannot skip a second occurrence (the outstanding-occurrence gate refuses it), but it answers 400 instead of the 200 the first delivery earned, so a client that retries should send a key.
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
Calendar date, ‘YYYY-MM-DD’
Examplegenerated
{ "occurrenceDate": "example"}Responses
Section titled “Responses”Advanced 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. VALIDATION_ERROR or BILL_OCCURRENCE_NOT_OUTSTANDING: the occurrence is not (or no longer) outstanding. BILL_EARLIER_OCCURRENCE_OUTSTANDING (KAN-3762): an EARLIER original-date occurrence of this bill in [cursor, occurrenceDate) is still outstanding and not exception-skipped, so this write would carry the cursor past an unpaid occurrence — fixed message ‘Enter or skip the earlier bill first.’, details.earliestOutstandingDate, no fieldErrors. ZERO writes; an idempotent replay of an earlier successful key is answered first, and the refused key is released (never poisoned). Never raised for a bill with a NULL cursor; GET /bills/scheduled exposes the same rule as enterBlockedByDate.
object
Optional field-level validation errors, keyed by field name.
object
object
The earliest EARLIER original-date occurrence of this bill still outstanding and not exception-skipped — the one to Enter or Skip first.
Example
{ "errorCode": "VALIDATION_ERROR"}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"}