Accounts & Balances

A Plaid account record represents an individual financial account (checking, savings, credit card, loan, etc.) within a user’s connected institution. Accounts are scoped to an item and are updated every time the mining pipeline runs for that item.

During Plaid connection, the user selects one account as their "main account." This is recorded on the item record (item_main_account_id) and is the account used for float disbursements and subscription collection. It should be a checking account into which the user’s paycheck is deposited. The system cannot verify this requirement, but enforces it as a convention.

Any other accounts within the item (additional checking, savings, credit cards, etc.) are also fetched and stored every time the miner calls Plaid.

See Plaid Mining Pipeline for how accounts are updated.

Storage

Table: prod-txn-transactions

Region: us-east-2

Keys

Key Value

PK

ACCOUNTS#<user_id>

SK

ACCOUNT#<account_id>

Attributes

Attribute Description

type

Always ACCOUNT

user_id

FloatMe user identifier

acct_id

Plaid-assigned account identifier. Generated by Plaid at connection time and stable for the life of the account.

acct_mask

Last 2–4 alphanumeric characters of the account number (e.g., "4242")

acct_name

Name or nickname of the account as set by the user or institution

acct_official_name

Official name of the account as reported by the institution (may differ from acct_name)

acct_subtype

Account subtype: checking, savings, credit card, money market, etc.

acct_type

Account type: depository, credit, loan, investment, other

acct_verification_status

Plaid verification status for the account (used for ACH eligibility)

institution_id

Plaid institution identifier for the institution this account belongs to

acct_balances

Balance object. See Balance Fields.

Balance Fields

The acct_balances attribute is a JSON object containing the most recent balance snapshot for the account. All monetary values are stored in cents.

Field Description

bal_available

Available balance in cents. The amount of funds that can be withdrawn. May be null if the institution does not report it.

bal_available_string

String representation of bal_available (e.g., "150.00")

bal_current

Current balance in cents. For depository accounts: total funds in the account. For credit accounts: total amount owed.

bal_current_string

String representation of bal_current

bal_limit

Credit limit in cents for credit accounts. null for depository accounts.

bal_limit_string

String representation of bal_limit

bal_iso_cc

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

bal_unofficial_cc

Unofficial currency code for non-ISO currencies

updated_date

RFC 3339 date when this balance was last retrieved from Plaid
bal_available may be null for some institution/account type combinations. When available is not reported by the bank, a calc_available value is computed from the current balance and pending transactions — this calculated value is emitted on the Kinesis stream but is not stored in DynamoDB.

Query Patterns

Query Index Conditions

List all accounts for a user

Primary

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

Get a specific account by user ID and account ID

Primary

PK = ACCOUNTS#<user_id>, SK = ACCOUNT#<acct_id>

Related Pages