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

# Payments

> Report monthly payments and understand auto-computed tradeline updates

Payments represent individual payment records against a tradeline. Each payment automatically updates the tradeline's status, balance, and 24-month payment history.

## Reporting a payment

```bash theme={null}
curl -X POST https://vvdufluovypptsnkihyv.supabase.co/functions/v1/payments \
  -H "x-api-key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tradeline_id": "9c843590-8552-4490-a50c-f0cc413d8b69",
    "payment_date": "2026-02-01",
    "period_start": "2026-02-01",
    "period_end": "2026-02-28",
    "amount_due": 150000,
    "amount_paid": 150000,
    "payment_status": "on_time"
  }'
```

### Request fields

| Field                 | Type    | Required | Description                                              |
| --------------------- | ------- | -------- | -------------------------------------------------------- |
| `tradeline_id`        | uuid    | Yes      | The tradeline this payment is for                        |
| `payment_date`        | string  | Yes      | YYYY-MM-DD — when the payment was made                   |
| `period_start`        | string  | No       | Billing period start (YYYY-MM-DD)                        |
| `period_end`          | string  | No       | Billing period end (YYYY-MM-DD)                          |
| `amount_due`          | integer | Yes      | Amount due this period in **cents**                      |
| `amount_paid`         | integer | Yes      | Amount actually paid in **cents**                        |
| `payment_status`      | enum    | Yes      | See [payment\_status enum](/guides/enums#payment_status) |
| `external_payment_id` | string  | No       | Your internal transaction ID. Max 255 chars.             |

### Response

The response includes the payment record plus a `tradeline_status` snapshot:

```json theme={null}
{
  "id": "1bedd1b0-aadd-4d0e-8d23-68b2f9d30efb",
  "tradeline_id": "9c843590-8552-4490-a50c-f0cc413d8b69",
  "payment_date": "2026-02-01",
  "amount_due": 150000,
  "amount_paid": 150000,
  "payment_status": "on_time",
  "reported": false,
  "tradeline_status": {
    "account_status": "current",
    "current_balance": 0,
    "amount_past_due": 0,
    "payment_history": "0"
  }
}
```

## Auto-updates on tradeline

When you report a payment, the API automatically:

1. **Updates `account_status`** based on `payment_status`
2. **Recalculates `current_balance`** from `amount_due - amount_paid`
3. **Updates `amount_past_due`** (non-zero when delinquent)
4. **Appends to `payment_history`** (24-month rolling string)
5. **Tracks `highest_balance`** if current balance exceeds previous high
6. **Sets `date_of_first_delinquency`** on first non-current payment

## Duplicate prevention

Each `(tradeline_id, period_start)` combination must be unique. Submitting a duplicate returns `409 CONFLICT`.

## Listing payments

Payments are listed per-tradeline. The `tradeline_id` query parameter is **required**.

```bash theme={null}
curl "https://vvdufluovypptsnkihyv.supabase.co/functions/v1/payments?tradeline_id=9c843590-8552-4490-a50c-f0cc413d8b69" \
  -H "x-api-key: sk_test_your_api_key_here"
```

Payments are ordered by `payment_date` descending.