Mark an occurrence as already paid out of band (declaration only)
const url = 'https://api.tovarifinancial.com/bills/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/mark-scheduled';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"occurrenceDate":"example","scheduledPaymentDate":"example","amountCents":1}'};
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/mark-scheduled \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "occurrenceDate": "example", "scheduledPaymentDate": "example", "amountCents": 1 }'The THIRD disposition of an outstanding occurrence, beside Enter and Skip. It records the user’s own assertion that they already paid this occurrence — typically weeks early — with the date and amount they actually paid, and every forecast surface then PRESENTS the occurrence at those values. It SETTLES NOTHING: no transaction is created, edited or reserved, no bill_payment_history row is written, and bills.nextPaymentDate is untouched. The occurrence stays outstanding and keeps its ORIGINAL occurrenceDate as its identity in every list, total, horizon and month it belongs to. Upsert on (bill, occurrence): re-marking with corrected values updates in place. X-Idempotency-Key is HONORED, and its fingerprint covers ALL FOUR submitted values (bill, occurrence, declared date, declared amount) rather than skip’s two — a mark is a form submission whose values ARE the request, so a resubmission with a corrected amount under the same key is refused 409 IDEMPOTENCY_CONFLICT rather than silently replaying the first envelope. The response carries no bill object and no effective values: a mark writes nothing to the bill, and clients refetch rather than patch.
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
The ORIGINAL scheduled occurrence date — the identity of the occurrence being marked, and the same value /enter and /skip take. NEVER the declared payment date.
When the user says they actually paid it. Unbounded in both directions by design (paying 30 days early is the point, and recording last week is equally valid); only a malformed date is refused, and no relation to occurrenceDate, to today, or to the next occurrence is enforced.
POSITIVE MAGNITUDE, integer minor units. Must be an integer > 0.
Examplegenerated
{ "occurrenceDate": "example", "scheduledPaymentDate": "example", "amountCents": 1}Responses
Section titled “Responses”Marked
object
object
Calendar date, ‘YYYY-MM-DD’
object
Calendar date, ‘YYYY-MM-DD’
Integer minor units (cents)
Examplegenerated
{ "data": { "billId": "example", "occurrenceDate": "example", "scheduledMark": { "scheduledPaymentDate": "example", "amountCents": 1 } }, "message": "example", "requestId": "example", "timestamp": "2026-04-15T12:00:00Z"}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"}