Skip to content

Turn credit-card statement details on or off

PUT
/settings/statement-details
curl --request PUT \
--url https://api.tovarifinancial.com/settings/statement-details \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "enabled": true }'

Body is exactly { "enabled": boolean }; an unknown key is a 400. X-Idempotency-Key is REQUIRED and store-backed: a replay of the same key and body returns the stored 200 and queues nothing again; the same key with a different body is a 409 IDEMPOTENCY_CONFLICT. Turning it ON needs the debt_planning capability (see the 403); it records the setting and, for each active connection with a credit card whose consent is granted or not yet checked, queues one statement fetch after the write commits. A connection whose Liabilities consent was checked and not granted is returned as ‘needs_relink’ and nothing is queued for it. Turning it OFF needs no capability, stops future fetches, keeps every stored statement, and does not stop a fee already started. The answer has the same shape as the GET.

X-Idempotency-Key
string

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.

Media typeapplication/json
object
enabled
required
boolean
Examplegenerated
{
"enabled": true
}

The setting after the write (also returned verbatim on an idempotent replay)

Media typeapplication/json
object
data
required
object
enabled
required

The household’s setting.

boolean
entitled
required

Whether the household holds debt_planning; a capability read error answers false.

boolean
fetchAvailable
required

Whether this environment’s statement fetch is armed.

boolean
items
required
Array<object>
object
itemId
required
string format: uuid
institutionName
required
string
nullable
creditCardAccountIds
required

The connection’s live credit-card accounts.

Array<string>
consent
required
string
Allowed values: granted not_granted unchecked
state
required

Derived server-side with the precedence off > needs_relink > checking_consent > reauth_required > fetch_paused > current > error > fetch_queued. error also covers a fetch requested more than 15 minutes ago with nothing fetched since.

string
Allowed values: off needs_relink checking_consent reauth_required fetch_paused current error fetch_queued
lastFetchedAt
required
string format: date-time
nullable
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
"data": {
"items": [
{
"consent": "granted",
"state": "off"
}
]
}
}

Validation failed — see errorCode / fieldErrors

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Missing, invalid, or expired bearer token

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
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. This operation can ALSO answer 403 with errorCode CAPABILITY_REQUIRED and no details, a refusal by the HANDLER rather than by the tenant gate: the request needs the debt_planning capability (the Premier plan or Founder access) — turning statement details on (enabled: true; turning it off needs no capability), or (KAN-4134) saving a non-null card payment field on a bill (clearing the mode needs none) or reading the card payment preview. It fails closed: a capability read that errors is refused the same way. Nothing is written, nothing is queued and no idempotency record is kept. It does NOT depend on CAPABILITY_FENCE_ENABLED or BILLING_ENABLED. The errorCode enum on this operation’s response schema is the complete, machine-readable list.

Media typeapplication/json
object
errorCode
required

Which condition refused the request, evaluated in this order (CCR-1). SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true; CAPABILITY_REQUIRED is unreachable while CAPABILITY_FENCE_ENABLED is not exactly true. The two switches are independent, so CAPABILITY_REQUIRED is reachable with the subscription paywall off. CAPABILITY_REQUIRED carries no details.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_REQUIRED CAPABILITY_REQUIRED
message
required
string
details
object
outstanding
required

Active policy versions the user has not yet accepted.

Array<object>
object
id
required
string format: uuid
policyType
required
string
version
required
integer
title
required
string
firstAcceptance
required

True when the user has accepted no policy before — the client renders the new-signup screen rather than the re-acceptance one.

boolean
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "EMAIL_NOT_VERIFIED"
}

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).

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}

Internal error (no internal detail leaked)

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
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.

Media typeapplication/json
object
errorCode
required

Machine-readable error code (AUTH_ERROR_CODES).

string
Allowed values: INVALID_EMAIL_FORMAT USER_ALREADY_EXISTS INVALID_INVITE_CODE WRONG_PASSWORD USER_NOT_FOUND AUTHENTICATION_FAILED EXPIRED_CODE INVALID_CODE INVALID_PASSWORD VALIDATION_ERROR SIGNUP_FAILED DATABASE_ERROR SERVICE_UNAVAILABLE PLAID_ERROR IDEMPOTENCY_CONFLICT ACCOUNT_ALREADY_LINKED NOT_FOUND
message
required
string
fieldErrors

Optional field-level validation errors, keyed by field name.

object
key
additional properties
Array<string>
requestId
required
string
timestamp
required
string format: date-time
Example
{
"errorCode": "INVALID_EMAIL_FORMAT"
}