Balance History

Balance history records store a time-series of account balance snapshots for a user’s connected Plaid accounts. A new snapshot is written every time the mining pipeline runs and receives updated account data from Plaid.

Balance history is used by underwriting and other downstream services to assess a user’s cash flow and eligibility for floats. Records have a TTL of 32 days by default, giving a rolling window of recent balance data.

See Plaid Mining Pipeline for when balance snapshots are captured (written by the refiner Lambda on every mining run).

Storage

Table: prod-txn-transactions

Region: us-east-2

Keys

Key Value

PK

BALANCE#<user_id>

SK

ACCOUNT#<acct_id>#<date>
The sort key uses ACCOUNT#<acct_id>#<date> which enables querying all balance history for a specific account in chronological order by using begins_with ACCOUNT#<acct_id>#.

Attributes

Attribute Description

user_id

FloatMe user identifier

account_id

Plaid account identifier

available

Available balance in cents at the time of the snapshot

current

Current balance in cents at the time of the snapshot

limit

Credit limit in cents (for credit accounts; null for depository accounts)

iso_cc

ISO 4217 currency code (e.g., USD)

updated_date

RFC 3339 date (YYYY-MM-DD) when this balance was received from Plaid

ttl

DynamoDB TTL Unix timestamp. Defaults to 32 days from updated_date. Records are automatically deleted by DynamoDB after this time.

Query Patterns

Query Index Conditions

Get balance history for a specific account

Primary

PK = BALANCE#<user_id>, SK begins_with ACCOUNT#<acct_id>#

Get balance history for a specific account within a date range

Primary

PK = BALANCE#<user_id>, SK between ACCOUNT#<acct_id>#<start_date> and ACCOUNT#<acct_id>#<end_date>

Get all balance history for a user (all accounts)

Primary

PK = BALANCE#<user_id>, SK begins_with ACCOUNT#

TTL and Retention

Balance history records have a 32-day rolling retention window configured via the account_balance_ttl_days Terraform variable (default: 32). When a record’s TTL expires, DynamoDB automatically deletes it.

The TTL is set at write time based on the updated_date. Because a new snapshot is written on every mining run, active users will have many snapshots within the 32-day window. Inactive users (no mining in >32 days) will have no balance history.

Related Pages