Items

A Plaid item represents a user’s connection to a specific financial institution. When a user links their bank account via Plaid Link, Plaid issues an item_id and access_token that are used for all subsequent calls to retrieve accounts, balances, transactions, and liabilities for that institution.

FloatMe supports multiple items per user, but at any given time only one item should be active. The user designates one account within an item as their "main account" — this is the checking account used for float disbursements and subscription collection.

See Item Lifecycle for add, update, and remove flows.

Storage

Table: prod-txn-plaid

Region: us-east-2

Keys

Key Value

PK

USERS#<user_id>

SK

ITEMS#<item_id>

GSI1PK

ITEMS#<item_id>

GSI1SK

USERS#<user_id> — required for GSI inclusion; not used for queries

Attributes

Attribute Description

type

Always ITEM

item_id

Plaid-assigned item identifier

item_user_id

FloatMe user_id

item_access_token

Plaid-assigned access token. Used for all Plaid API calls (transactions, accounts, balances, auth, liabilities) for this item.

item_institution_id

Plaid institution identifier

item_institution_name

Human-readable institution name

item_error_code

Current error state. See Item Error Codes.

item_transactions_last_successful_update

Timestamp of the last successful transaction mine

item_transactions_last_failed_update

Timestamp of the last failed transaction mine attempt

item_last_webhook_sent_at

Timestamp of the most recent Plaid webhook received for this item

item_last_webhook_code_sent

Webhook code of the most recently received Plaid webhook (e.g., DEFAULT_UPDATE)

item_main_account_id

Plaid account_id of the user’s designated main account for float disbursements and subscription collection

item_status

Current lifecycle status. See Item Statuses.

item_created_at

RFC3339 timestamp when the item was created

item_updated_at

RFC3339 timestamp of the last update

item_removed_at

RFC3339 timestamp when the item was removed (only set when item_status = REMOVED)

Item Statuses

Status Description

ACTIVE

Item is connected and healthy. Transactions and accounts are being mined.

ERROR

Item has an error. See item_error_code for the specific cause. User must re-authenticate via Plaid Link update mode to resolve ITEM_LOGIN_REQUIRED.

REMOVED

Item has been disconnected. The Plaid access token has been revoked. No further mining occurs.

Item Error Codes

item_error_code Description

ITEM_LOGIN_REQUIRED

The user’s bank credentials have expired or changed. The user must re-authenticate.

NO_ACCOUNTS

No accessible accounts were found within the item.

(empty)

No error — item is healthy.

Query Patterns

Query Index Conditions

Get item by user ID and item ID

Primary

PK = USERS#<user_id>, SK = ITEMS#<item_id>

List all items for a user

Primary

PK = USERS#<user_id>, SK begins_with ITEMS#

Get item by item ID (cross-user lookup)

GSI1

GSI1PK = ITEMS#<item_id>

Related Pages