> ## Documentation Index
> Fetch the complete documentation index at: https://new.cove.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tradelines

> Manage tradelines — ongoing payment obligations reported to credit bureaus

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

```bash theme={null}
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](/guides/enums#payment_type) |
| `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](/guides/enums#payment_frequency)      |
| `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](/guides/enums#ecoa_code)                      |
| `metro2_account_type`  | enum      | `revolving`  | See [metro2\_account\_type enum](/guides/enums#metro2_account_type) |
| `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.

<Warning>Closed tradelines cannot be re-opened. Create a new tradeline instead.</Warning>

## 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`.