Save the planning window and cushion
const url = 'https://api.tovarifinancial.com/settings/safe-to-spend';const options = { method: 'PUT', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"paycheckWindow":1,"cushionMode":"automatic","cushionFixedCents":1,"updatedAt":"example"}'};
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/settings/safe-to-spend \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "paycheckWindow": 1, "cushionMode": "automatic", "cushionFixedCents": 1, "updatedAt": "example" }'FULL REPLACE, NOT A PATCH — both settings sit on one form behind one Save button — and unknown keys are rejected outright rather than ignored. updatedAt is REQUIRED even when null: it is the opaque concurrency token from the last GET or PUT, and an explicit null is the positive assertion “I believe there is no row yet”, honoured only when the server agrees. A token that does not match the stored one is a 409 STALE_WRITE carrying the WINNING record; nothing is written. cushionFixedCents is persisted independently of cushionMode, so switching to Automatic does not wipe the amount typed earlier — but omitting it while cushionMode is fixed is a 400. The 200 is recomputed AFTER the write commits, so it reflects what actually landed.
X-Idempotency-Key is honoured HERE and is reconciled on the row’s own last_write_idempotency_key, not through the shared idempotency store. The key is checked BEFORE the compare-and-set: the same key with the same body is a redelivery and answers 200 with the current record, writing nothing, rather than reporting a conflict nobody caused; the same key with a DIFFERENT body answers 409 IDEMPOTENCY_CONFLICT with no details and writes nothing, even when its updatedAt is also stale. So this operation’s 409 carries one of two codes: STALE_WRITE or IDEMPOTENCY_CONFLICT.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”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
Planning window counted in scheduled paychecks.
Integer minor units, 1..100000000. Required when cushionMode is fixed; omit the key to leave the stored amount untouched. 0 is a 400 — a $0 fixed cushion and “automatic with no history” would otherwise be the same row meaning opposite things.
The opaque token from the last GET/PUT. REQUIRED as a key; null asserts that no row existed.
Responses
Section titled “Responses”The saved settings, recomputed after commit (also returned verbatim on an idempotent replay)
object
object
object
Planning window counted in scheduled paychecks.
Integer minor units. Persisted independently of cushionMode; null when never set.
The OPAQUE concurrency token — round-trip it verbatim on the next PUT. Never parse or format it; null when no row exists yet.
FALSE when no row exists: these are the defaults and the household never chose them. An absent row is a 200, never a 404.
object
Integer minor units (cents)
Integer minor units (cents)
Server-authored ceiling copy. Render THIS string — never a client-side number.
object
Calendar date, ‘YYYY-MM-DD’
Exactly three, ordered paycheckWindow 1,2,3 — the settings screen previews a change by selecting over these rather than by a second request.
object
Planning window counted in scheduled paychecks.
The figure the dashboard will render after saving THIS window, to the cent.
Always resolved — end-of-month when windowIsFallback.
Equals paycheckWindow unless windowIsFallback, when it is 0.
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
Example
{ "data": { "settings": { "paycheckWindow": 1, "cushionMode": "automatic" }, "projections": [ { "paycheckWindow": 1 } ] }}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"}Nothing was written. STALE_WRITE: the compare-and-set on updatedAt failed — someone else saved while this caller was editing; details.current is the winning record in the SAME shape the 200 carries, so a client can seed its cache with it directly. IDEMPOTENCY_CONFLICT: the X-Idempotency-Key was reused with a different body; no details. The same key with the same body answers 200, never this status.
object
STALE_WRITE: the compare-and-set on the opaque updated_at token failed — someone else saved while this caller was editing. IDEMPOTENCY_CONFLICT: the X-Idempotency-Key was already used for a save with a DIFFERENT body; do not retry with the same key. Nothing was written in either case.
Present ONLY on STALE_WRITE (absent on IDEMPOTENCY_CONFLICT). The conflict context. current is the WINNING record in the SAME shape the 200 carries — the bare GET payload, never re-wrapped — so a client can seed its cache with it directly.
object
object
object
Planning window counted in scheduled paychecks.
Integer minor units. Persisted independently of cushionMode; null when never set.
The OPAQUE concurrency token — round-trip it verbatim on the next PUT. Never parse or format it; null when no row exists yet.
FALSE when no row exists: these are the defaults and the household never chose them. An absent row is a 200, never a 404.
object
Integer minor units (cents)
Integer minor units (cents)
Server-authored ceiling copy. Render THIS string — never a client-side number.
object
Calendar date, ‘YYYY-MM-DD’
Exactly three, ordered paycheckWindow 1,2,3 — the settings screen previews a change by selecting over these rather than by a second request.
object
Planning window counted in scheduled paychecks.
The figure the dashboard will render after saving THIS window, to the cent.
Always resolved — end-of-month when windowIsFallback.
Equals paycheckWindow unless windowIsFallback, when it is 0.
Integer minor units (cents)
Integer minor units (cents)
Integer minor units (cents)
The household member who saved. Null for a removed or unnamed member (render “Someone”) — never an email address.
ALWAYS a string: the winning row’s timestamp, or the recompute time in the asymmetric case where no row exists.
Example
{ "errorCode": "STALE_WRITE", "details": { "current": { "settings": { "paycheckWindow": 1, "cushionMode": "automatic" }, "projections": [ { "paycheckWindow": 1 } ] } }}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"}