Skip to content

A credit card's statement details, user-entered terms and credit limit

GET
/accounts/{id}/statement-details
curl --request GET \
--url https://api.tovarifinancial.com/accounts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/statement-details \
--header 'Authorization: Bearer <token>'

READ-ONLY (KAN-4132): no idempotency key. Credit cards only — any other account type, a missing id and another org’s account are the IDENTICAL 404. userTerms and creditLimit are always returned. statement and history are returned only when the household holds the debt_planning capability (a capability read error counts as not entitled): otherwise status is ‘not_entitled’, statement null and history []. statement is non-null whenever the household is entitled and a statement has been stored, independent of status. status is derived server-side with the precedence not_entitled > not_linked > not_enabled > needs_relink > checking_consent > reauth_required > fetch_paused > available > error > pending_first_fetch. Statement amounts are OWED-POSITIVE integer cents as the bank reports them (a negative statement balance is a credit balance), unlike the ledger’s signed balances. history is first-seen per closing date, newest first, at most 24 rows; Plaid reports only the latest statement, so nothing before the first refresh exists. KAN-4135: institutionName, userTerms and credit are always returned; lastReconciledStatement, historySummary and the statement / history[] additions are entitled-only (null / [] otherwise). Every figure is server-computed; daysUntilDue and the newest paidTowardThroughDate use the client’s today (X-Client-Timezone).

id
required
string format: uuid

Account id

Statement details

Media typeapplication/json
object
data
required
object
accountId
required
string format: uuid
institutionName
required

KAN-4135 — the live link’s institution name; null = not linked.

string
nullable
userTerms
required
object
annualFeeCents
required

Integer minor units (cents)

integer format: int64
nullable
annualFeeMonth
required
integer
nullable >= 1 <= 12
promoEndDate
required

KAN-4135 — user-entered.

string
nullable
postPromoAprPercent
required

KAN-4135 — user-entered, an exact decimal string.

string
nullable
statementCheckEnabled
required

KAN-4135 — the per-card automatic statement check.

boolean
creditLimit
required
object
cents
required

Integer minor units (cents)

integer format: int64
nullable
source
required
string
nullable
Allowed values: user plaid
credit
required

KAN-4135 — credit used against the limit (computeCreditUtilization); null with no usable limit.

object
owedCents
required

Integer minor units (cents)

integer format: int64
availableCents
required

Integer minor units (cents)

integer format: int64
utilizationPct
required

Rounded whole percent; may exceed 100 over the limit.

integer
tier
required
string
Allowed values: low medium high
status
required
string
Allowed values: available not_entitled not_enabled not_linked checking_consent needs_relink pending_first_fetch fetch_paused reauth_required error
statement
required
object
lastStatementBalanceCents
required

Integer minor units (cents)

integer format: int64
nullable
lastStatementIssueDate
required

The closing date, ‘YYYY-MM-DD’.

string
nullable
minimumPaymentCents
required

Integer minor units (cents)

integer format: int64
nullable
nextPaymentDueDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
lastPaymentCents
required

Integer minor units (cents)

integer format: int64
nullable
lastPaymentDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
isOverdue
required
boolean
nullable
promoEndDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
postPromoAprPercent
required

Exact decimal string; no writer yet, so always null today.

string
nullable
aprs
required
Array<object>
object
type
required

Plaid’s apr_type, normalized; a type the server does not recognize is ‘other’.

string
Allowed values: purchase_apr balance_transfer_apr cash_apr special other
aprPercent
required

The rate as an EXACT decimal string (at most 4 places), never a JSON number.

string
/^\d{1,3}(\.\d{1,4})?$/
balanceSubjectToAprCents
required

Integer minor units (cents)

integer format: int64
nullable
interestChargeCents
required

Integer minor units (cents)

integer format: int64
nullable
fetchedAt
required
string format: date-time
interestChargedCents
required

KAN-4135 — the sum of the APRs’ interest; null when none is reported.

integer format: int64
nullable
paidSinceStatementCents
required

KAN-4135 — card payments since the closing date, >= 0.

integer format: int64
nullable
daysUntilDue
required

KAN-4135 — due date minus the client’s today; negative = past due.

integer
nullable
promo
required

KAN-4135 — the bank’s promo fields when either is set, else the user’s, else null.

object
endDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
postPromoAprPercent
required
string
nullable
source
required
string
Allowed values: bank user
lastReconciledStatement
required

KAN-4135 — the newest statement that reads reconciled, and the action that reconciled it.

object
statementId
required
string format: uuid
closingDate
required

Calendar date, ‘YYYY-MM-DD’

string
reconciledAt
required
string format: date-time
reconciledCount
required
integer
historySummary
required

KAN-4135 — the KPI strip over the newest up to 6 statements; deltas are newest minus oldest in the window (null when either is null or under 2 rows). null for an empty history.

object
statementCount
required
integer
<= 6
interestTotalCents
required

Integer minor units (cents)

integer format: int64
interestDeltaCents
required

Integer minor units (cents)

integer format: int64
nullable
balanceDeltaCents
required

Integer minor units (cents)

integer format: int64
nullable
sinceClosingDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
history
required
Array<object>
<= 24 items
object
closingDate
required

Calendar date, ‘YYYY-MM-DD’

string
statementBalanceCents
required

Integer minor units (cents)

integer format: int64
nullable
minimumPaymentCents
required

Integer minor units (cents)

integer format: int64
nullable
paymentDueDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
aprs
required
Array<object>
object
type
required

Plaid’s apr_type, normalized; a type the server does not recognize is ‘other’.

string
Allowed values: purchase_apr balance_transfer_apr cash_apr special other
aprPercent
required

The rate as an EXACT decimal string (at most 4 places), never a JSON number.

string
/^\d{1,3}(\.\d{1,4})?$/
balanceSubjectToAprCents
required

Integer minor units (cents)

integer format: int64
nullable
interestChargeCents
required

Integer minor units (cents)

integer format: int64
nullable
recordedAt
required
string format: date-time
id
required

KAN-4133 — the statement history row id (the {statementId} of the fix/undo routes).

string format: uuid
interestChargedCents
required

KAN-4135 — the sum of the APRs’ interest; null when none.

integer format: int64
nullable
paidTowardCents
required

KAN-4135 — card payments in (closingDate, paidTowardThroughDate], >= 0.

integer format: int64
paidTowardThroughDate
required

KAN-4135 — the next newer closing date, or the client’s today.

string
paidTowardLastDate
required

KAN-4135 — the newest payment in that window.

string
nullable
fixTransactions
required
Array<object>
object
transactionId
required
string format: uuid
date
required

Calendar date, ‘YYYY-MM-DD’

string
amountCents
required

Integer minor units (cents)

integer format: int64
payeeName
required
string
nullable
daysAfterClosing
required
integer
check
required

KAN-4133 — the statement check result, or null when the statement has not been checked yet.

object
statementId
required
string format: uuid
closingDate
required

Calendar date, ‘YYYY-MM-DD’

string
periodStart
required

Calendar date, ‘YYYY-MM-DD’

string
resolutionState
required
string
Allowed values: needs_review auto_reconciled resolved left_open superseded
checkedAt
required
string format: date-time
rulesVersion
required
integer
balance
required
object
status
required
string
Allowed values: pass fail unavailable
expectedLedgerCents
required

Integer minor units (cents)

integer format: int64
nullable
actualLedgerCents
required

Integer minor units (cents)

integer format: int64
nullable
differenceLedgerCents
required

Integer minor units (cents)

integer format: int64
nullable
pendingInPeriodCount
required
integer
breakdown

KAN-4135 — “How it adds up”, ledger-signed: opening + payments + interest + purchasesAndCredits equals actualLedgerCents exactly (purchasesAndCredits is the residual). null for a check written before the breakdown shipped.

object
openingLedgerCents
required

Integer minor units (cents)

integer format: int64
paymentsLedgerCents
required

Integer minor units (cents)

integer format: int64
interestLedgerCents
required

Integer minor units (cents)

integer format: int64
purchasesAndCreditsLedgerCents
required

Integer minor units (cents)

integer format: int64
openingDate
required

The day before the period (‘YYYY-MM-DD’), computed at read time.

string
interest
required
object
status
required
string
Allowed values: pass fail unavailable
expectedCents
required

Integer minor units (cents)

integer format: int64
nullable
actualCents
required

Integer minor units (cents)

integer format: int64
nullable
differenceCents
required

Integer minor units (cents)

integer format: int64
nullable
minimumPayment
required
object
status
required
string
Allowed values: pass flag unavailable
flags
required
Array<string>
Allowed values: no_payment_scheduled below_minimum after_due_date minimum_jumped
billId
required
string format: uuid
nullable
scheduledDate
required

Calendar date, ‘YYYY-MM-DD’

string
nullable
scheduledCents
required

Integer minor units (cents)

integer format: int64
nullable
fees
required
object
status
required
string
Allowed values: pass flag
items
required
Array<object>
object
transactionId
required
string format: uuid
kind
required
string
Allowed values: late foreign_transaction cash_advance annual other
amountCents
required

Integer minor units (cents)

integer format: int64
expected
required
boolean
offeredFixes
required
Array
One of:
object
kind
required
string
Allowed values: move
transactionId
required
string format: uuid
ledgerAmountCents
required

Integer minor units (cents)

integer format: int64
fromDate
required

Calendar date, ‘YYYY-MM-DD’

string
activeActions
required
Array<object>
object
id
required
string format: uuid
kind
required
string
Allowed values: auto_reconcile move adjustment add_interest leave_open
createdAt
required
string format: date-time
undoneAt
required
string format: date-time
nullable
reconciledCount
required
integer
amountCents
required

The LEDGER-signed amount of the row the fix wrote, else null.

integer format: int64
nullable
movedTransactionId
required
string format: uuid
nullable
addedTransactionId
required
string format: uuid
nullable
message
string
requestId
required
string
timestamp
required
string format: date-time
Example
{
"data": {
"creditLimit": {
"source": "user"
},
"credit": {
"tier": "low"
},
"status": "available",
"statement": {
"aprs": [
{
"type": "purchase_apr"
}
],
"promo": {
"source": "bank"
}
},
"history": [
{
"aprs": [
{
"type": "purchase_apr"
}
],
"check": {
"resolutionState": "needs_review",
"balance": {
"status": "pass"
},
"interest": {
"status": "pass"
},
"minimumPayment": {
"status": "pass",
"flags": [
"no_payment_scheduled"
]
},
"fees": {
"status": "pass",
"items": [
{
"kind": "late"
}
]
},
"offeredFixes": [
{
"kind": "move"
}
],
"activeActions": [
{
"kind": "auto_reconcile"
}
]
}
}
]
}
}

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.

Media typeapplication/json
object
errorCode
required

Which precondition refused the request. Evaluated in this order (CCR-1); SUBSCRIPTION_REQUIRED is unreachable while BILLING_ENABLED is not exactly true.

string
Allowed values: EMAIL_NOT_VERIFIED POLICY_ACCEPTANCE_REQUIRED SUBSCRIPTION_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"
}

Resource not found or not owned by the caller org

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"
}