Liabilities

A liability record represents a debt account within a user’s connected institution. Plaid supports three liability types: credit cards, mortgages, and student loans. Each type has a distinct set of fields in addition to the shared base fields.

Liability mining is controlled by the ENABLE_LIABILITY_MINING feature flag (enabled in test, currently disabled in prod). When enabled, the miner Lambda processes LIABILITIES / DEFAULT_UPDATE webhooks to fetch and store the latest liability data from Plaid.

Two record types are maintained for each liability:

  • Current liability — Always reflects the most recent data from Plaid. Overwritten on each update.

  • Liability history — An append-only log. A new history record is written for every fetched snapshot with no deduplication; StoreLiability unconditionally appends a timestamped history item on each call.

Storage

Table: prod-txn-plaid

Region: us-east-2

Current Liability Keys

Key Value

PK

LIABILITIES#<user_id>

SK

ITEM#<item_id>#ACCOUNT#<account_id>

GSI1PK

LIABILITIES#<account_id>

GSI1SK

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

Liability History Keys

Key Value

PK

LIABILITY_HISTORY#<user_id>

SK

ITEM#<item_id>#ACCOUNT#<account_id>#TIMESTAMP#<timestamp>

GSI1PK

LIABILITY_HISTORY#<account_id>

GSI1SK

TIMESTAMP#<timestamp>

GSI2PK

LIABILITY_HISTORY#<user_id>

GSI2SK

TIMESTAMP#<timestamp>

Shared Attributes

All liability records include these fields regardless of type:

Attribute Description

item_id

Plaid-assigned item identifier

account_id

Plaid-assigned account identifier

user_id

FloatMe user identifier

type

Liability type: CREDIT, MORTGAGE, or STUDENT

last_payment_amount

Amount of the most recent payment, in cents

last_payment_date

RFC 3339 date of the most recent payment

next_payment_due_date

RFC 3339 date when the next payment is due

Credit Liability Attributes

Attribute Description

aprs

Array of APR (Annual Percentage Rate) objects. See APR Fields.

is_overdue

true if the account has an overdue payment

last_statement_issue_date

RFC 3339 date when the most recent statement was issued

last_statement_balance

Balance on the most recent statement, in cents

minimum_payment_amount

Minimum payment amount due, in cents

APR Fields

Each entry in the aprs array represents one APR tier on the credit account:

Field Description

apr_percentage

APR as a decimal percentage (e.g., 22.99)

apr_type

Type of APR (e.g., purchase_apr, cash_apr, balance_transfer_apr, special)

balance_subject_to_apr

Balance amount currently subject to this APR, in cents

interest_charge_amount

Interest charge for this APR tier in the current period

Mortgage Liability Attributes

Attribute Description

interest_rate

Interest rate object. See Mortgage Interest Rate.

loan_type_description

Description of the mortgage loan type (e.g., "conventional", "FHA", "VA")

maturity_date

RFC 3339 date when the mortgage is scheduled to be fully paid off

next_monthly_payment

Next scheduled monthly payment amount, in cents

origination_date

RFC 3339 date when the mortgage was originated

origination_principal_amount

Original principal amount of the mortgage, in cents

escrow_balance

Current escrow account balance, in cents

has_pmi

true if the mortgage has Private Mortgage Insurance

has_prepayment_penalty

true if the mortgage has a prepayment penalty

property_address

Address of the mortgaged property

current_late_fee

Current late fee balance, in cents

ytd_interest_paid

Year-to-date interest paid, in cents

ytd_principal_paid

Year-to-date principal paid, in cents

Mortgage Interest Rate

Field Description

interest_rate_percentage

Interest rate as a string (e.g., "6.75")

interest_rate_type

Rate type: fixed or variable

Student Loan Liability Attributes

Attribute Description

loan_name

Name of the loan as reported by the servicer (e.g., "Subsidized Stafford")

loan_status

Loan status object. See Student Loan Status.

repayment_plan

Repayment plan object. See Repayment Plan.

disbursement_dates

Array of RFC 3339 dates when loan funds were disbursed

expected_payoff_date

RFC 3339 date when the loan is expected to be paid off under the current plan

guarantor

Name of the loan guarantor (e.g., "PHEAA")

interest_rate_percentage

Annual interest rate as a string (e.g., "4.53")

is_overdue

true if the account has an overdue payment

last_statement_issue_date

RFC 3339 date when the most recent statement was issued

minimum_payment_amount

Minimum payment amount due, in cents

origination_date

RFC 3339 date when the loan was originated

origination_principal_amount

Original principal amount of the loan, in cents

outstanding_interest_amount

Total interest accrued but not yet paid, in cents

payment_reference_number

Payment reference number used by the servicer

sequence_number

Sequence number identifying this loan among multiple loans from the same servicer

ytd_interest_paid

Year-to-date interest paid, in cents

ytd_principal_paid

Year-to-date principal paid, in cents

Student Loan Status

Field Description

status_type

Status of the loan (e.g., repayment, in_school, grace_period, deferral, forbearance, delinquent, defaulted, paid_in_full)

status_end_date

RFC 3339 date when the current status is expected to end

Repayment Plan

Field Description

repayment_plan_type

Type of repayment plan (e.g., standard, income_contingent_repayment, graduated, extended, income_based_repayment)

repayment_plan_description

Human-readable description of the repayment plan

Query Patterns

Query Index Conditions

Get all current liabilities for a user

Primary

PK = LIABILITIES#<user_id>, SK begins_with ITEM#

Get current liability for a specific item and account

Primary

PK = LIABILITIES#<user_id>, SK = ITEM#<item_id>#ACCOUNT#<account_id>

Get liability history for a specific user, item, and account (sorted by time)

Primary

PK = LIABILITY_HISTORY#<user_id>, SK begins_with ITEM#<item_id>#ACCOUNT#<account_id>#TIMESTAMP#

Update Behavior

When a new liability snapshot arrives from Plaid:

  1. The current liability record (LIABILITIES#<user_id> / ITEM#<item_id>#ACCOUNT#<account_id>) is overwritten with the latest data.

  2. A new history record is unconditionally appended with a timestamped sort key (TIMESTAMP#<timestamp>). There is no deduplication — every fetched snapshot produces a history entry.

This means the history table contains one entry per mining run, regardless of whether the data changed.

Related Pages