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"}'};
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" }'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 deliberately fingerprinted over {billId, occurrenceDate} ONLY: settleAgainstTransactionId is excluded so that the documented attempt -> 409 BILL_PENDING_MATCH_UNCONFIRMED -> re-issue-the-same-key-with-the-token flow completes rather than conflicting. 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. Two cases, told apart per operation: (1) where the operation also documents a 409, 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.
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.
Examplegenerated
{ "occurrenceDate": "example", "settleAgainstTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "confirmPendingMatchTransactionId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"}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’
Calendar date, ‘YYYY-MM-DD’
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
object
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" }, "affectedBudget": [ { "month": "2026-07" } ] }}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"}Either IDEMPOTENCY_CONFLICT (the key was already used for a different bill or a different occurrenceDate) or 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). Nothing was written in either case.
object
object
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"}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"}