Post a scheduled occurrence into the register
const url = 'https://api.tovarifinancial.com/bills/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/enter';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"occurrenceDate":"example","settleAgainstTransactionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","confirmPendingMatchTransactionId":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","postWithoutSettling":true,"amountCents":1,"settleOnly":true}'};
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/enter \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "occurrenceDate": "example", "settleAgainstTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "confirmPendingMatchTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "postWithoutSettling": true, "amountCents": 1, "settleOnly": true }'X-Idempotency-Key is HONORED (KAN-1302), through the shared idempotency store. A redelivery of the same key for the same bill and occurrenceDate replays the recorded envelope byte for byte — including its original 201 on a first insert — and posts nothing a second time; the same key carrying a different occurrenceDate, or aimed at a different bill, is refused 409 IDEMPOTENCY_CONFLICT. The key is fingerprinted over {billId, occurrenceDate, amountCents, settleOnly} (KAN-3604), where amountCents and settleOnly are included ONLY when present (settleOnly only when true), so a request without them fingerprints exactly as before and the same key carrying a different amountCents is 409 IDEMPOTENCY_CONFLICT. settleAgainstTransactionId and postWithoutSettling are excluded so that the documented attempt -> 409 BILL_PENDING_MATCH_UNCONFIRMED -> re-issue-the-same-key-with-the-token flow completes rather than conflicting. With no amountCents, a newly posted row carries the occurrence’s effective amount (declaration, else forecast override, else series). The key is optional — an unkeyed request behaves exactly as before — but the write is NOT convergent without one, so a client that retries should always send it.
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’
Confirms settling this occurrence against an already-matched bank row — normally details.pendingMatch.transactionId from this route’s own 409. Re-issue the SAME X-Idempotency-Key with it: the fingerprint deliberately excludes this field.
Legacy alias for settleAgainstTransactionId. Prefer the live name.
The user’s “none of these” answer to this route’s 409 BILL_MATCH_AMBIGUOUS (KAN-2396): post the occurrence as its own register row. Must be a boolean; cannot be combined with settleAgainstTransactionId or with settleOnly:true. Excluded from the idempotency fingerprint.
OPTIONAL amount to post, as a POSITIVE MAGNITUDE in integer minor units (KAN-3604) — the sign is re-derived from the bill’s direction by the server. Used ONLY when the occurrence posts as a new register row; every settle-against-an-existing-bank-row path ignores it and keeps the bank row’s amount. When omitted, the server posts the occurrence’s EFFECTIVE amount: its declaration amount, else its forecast override, else the series amount. 0, a negative, a non-integer, a non-number, null or an unsafe integer is a 400. Part of the idempotency fingerprint when present.
OPTIONAL (KAN-3604). true means “claim the bank row named by settleAgainstTransactionId, or do nothing” — the call NEVER inserts a register row. Requires settleAgainstTransactionId and cannot be combined with postWithoutSettling:true (both 400). When the named row can no longer be claimed the call answers 409 BILL_SETTLE_TARGET_UNAVAILABLE with zero writes. Part of the idempotency fingerprint only when true.
Examplegenerated
{ "occurrenceDate": "example", "settleAgainstTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "confirmPendingMatchTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "postWithoutSettling": true, "amountCents": 1, "settleOnly": true}Responses
Section titled “Responses”Posted transaction + advanced bill
object
object
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
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)
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
object
Month, ‘YYYY-MM’
Integer minor units (cents)
Integer minor units (cents)
Example
{ "data": { "bill": { "direction": "expense", "frequency": "once", "endType": "never", "occurrenceStatus": "upcoming", "autoEnterMode": "automatic", "outOfBandMatch": { "status": "cleared", "reason": "amount_differs" }, "effectiveToleranceCents": { "source": "manual" } }, "affectedBudget": [ { "month": "2026-07" } ] }}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"}IDEMPOTENCY_CONFLICT (the key was already used for a different bill, occurrenceDate, amountCents or settleOnly), BILL_PENDING_MATCH_UNCONFIRMED (a pending bank row already covers this occurrence; details.pendingMatch names it, and the caller re-issues the SAME key with settleAgainstTransactionId to confirm) or BILL_SETTLE_TARGET_UNAVAILABLE (a settleOnly:true call whose named bank row can no longer be claimed; no details) or BILL_MANUAL_ENTRY_UNCONFIRMED (KAN-3764 — the occurrence is covered by a row the user typed into the register and the call neither named it in settleAgainstTransactionId nor sent postWithoutSettling: true, or the token names one of the household’s own hand-typed rows that no longer covers it; details.manualEntryMatch names the covering row, or is null). Nothing was written in any case.
object
object
Present ONLY on BILL_MANUAL_ENTRY_UNCONFIRMED (KAN-3764). Non-null: the row the user typed into the register that already covers this occurrence — re-issue the SAME key with settleAgainstTransactionId set to its transactionId to settle against it, or with postWithoutSettling: true to post anyway. Null: the named token is one of the household’s own hand-typed rows that no longer covers this occurrence — refresh the scheduled bills.
object
Calendar date, ‘YYYY-MM-DD’
SIGNED ledger cents, exactly as stored.
Present ONLY on BILL_MANUAL_ENTRY_UNCONFIRMED (KAN-3764), and only when the occurrence is ALSO ambiguous (two or more tied bank rows): the same chooser GET /bills/scheduled offers, carrying at least two entries. Re-issue the SAME key with settleAgainstTransactionId set to one of their transactionIds to settle against that bank row instead; any other token is answered with this same refusal.
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.
object
SIGNED ledger cents, exactly as stored.
Calendar date, ‘YYYY-MM-DD’
transactions.description — the text already on the user’s screen. NEVER the raw bank descriptor.
Example
{ "errorCode": "IDEMPOTENCY_CONFLICT", "details": { "ambiguousMatches": [ { "status": "cleared" } ] }}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"}