Tradelines

A tradeline represents an ongoing payment obligation (rent, child support, loan, etc.) being reported to credit bureaus. Each tradeline belongs to a consumer and tracks a specific payment type.

Creating a tradeline

curl -X POST https://vvdufluovypptsnkihyv.supabase.co/functions/v1/tradelines \
  -H "x-api-key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "consumer_id": "d1ba6184-b708-4e76-91fc-85dd6443c890",
    "payment_type": "child_support",
    "account_opened_date": "2025-01-01",
    "payment_amount": 150000,
    "metro2_account_type": "installment"
  }'

Required fields

Field	Type	Description
`consumer_id`	uuid	The consumer this tradeline belongs to
`payment_type`	enum	See payment_type enum
`account_opened_date`	string	YYYY-MM-DD — when the obligation began
`payment_amount`	integer	Monthly expected payment in cents

Optional fields

Field	Type	Default	Description
`payment_type_label`	string	null	Human-readable label
`external_account_id`	string	null	Your internal account/case ID
`payment_frequency`	enum	`monthly`	See payment_frequency enum
`credit_limit`	integer	null	In cents (for revolving accounts)
`highest_balance`	integer	null	In cents
`original_loan_amount`	integer	null	In cents (for installment accounts)
`ecoa_code`	enum	`individual`	See ecoa_code enum
`metro2_account_type`	enum	`revolving`	See metro2_account_type enum
`report_to_bureaus`	string[]	All three	Which bureaus to report to

Auto-computed fields

These fields are managed automatically and should not be set manually:

Field	Description
`account_status`	Derived from the latest `payment_status`
`current_balance`	Computed from `amount_due - amount_paid` across periods
`amount_past_due`	Sum of unpaid balances
`payment_history`	24-char Metro 2 history string (newest first)
`date_of_first_delinquency`	Set on first non-current payment
`highest_balance`	Updated when balance exceeds previous high

Updating a tradeline

Only mutable fields can be updated via PATCH: Can change: payment_type_label, credit_limit, highest_balance, ecoa_code, report_to_bureaus, is_active, account_closed_date Cannot change: consumer_id, payment_type, account_opened_date

Closing a tradeline

DELETE /tradelines/:id closes the tradeline (it’s not a hard delete):

Sets account_status to "closed"
Sets is_active to false
Sets account_closed_date to today

The tradeline remains visible in list results and via GET, but will no longer accept new payments.

Closed tradelines cannot be re-opened. Create a new tradeline instead.

Authorization

The payment_type must be in the partner’s enabled_payment_types list (if configured). If not, you’ll get a 403 AUTHORIZATION_ERROR.

Getting Started

Core Concepts

Reference

Migration

Creating a tradeline

Required fields

Optional fields

Auto-computed fields

Updating a tradeline

Closing a tradeline

Authorization

​Creating a tradeline

​Required fields

​Optional fields

​Auto-computed fields

​Updating a tradeline

​Closing a tradeline

​Authorization

Creating a tradeline

Required fields

Optional fields

Auto-computed fields

Updating a tradeline

Closing a tradeline

Authorization