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

# v2 API changelog

> Changes to v2 API endpoints, objects, and documentation, from preview through general availability.

This page records changes to the v2 API after an endpoint is published. Each entry is tagged with the endpoint's stage at the time of the change.

* Preview The endpoint can change without advance notice, including breaking changes.
* Beta Breaking changes are announced on the [Upcoming Changes](https://docs.lead.bank/upcoming-changes.md) page before they ship.
* GA Changes follow the commitments on [Versioning and Backwards Compatibility](https://docs.lead.bank/core-concepts/platform/versioning-and-backwards-compatibility.md).

Changes to v1 are on the [v1 changelog](https://docs.lead.bank/changelog.md).

**Nov 17, 2026**

## User Credit Balance Terms Block

### **Why We Made This Change**

An API standards review found names in the User Credit Balance API that repeat their block's name, or that don't say what a block holds. The `details` block holds the loan's terms, and the rates describe those same terms. The API is in preview, so these changes ship without a new API version.

### **What Changed**

| Before | After |
| - | - |
| `details` | `terms` |
| `details.term` | `terms.duration` |
| `interest.rate` | `terms.interest_rate` |
| `interest.effective_rate` | `terms.effective_interest_rate` |
| `interest.effective_apr` | `terms.effective_apr` |
| `past_due.past_due_days` | `past_due.days` |

The `interest` block no longer exists. `amount_breakdown.interest` is unchanged. The `expected_` names inside `terms` are unchanged.

### **What You Need To Do**

1. Send the three rates and `structure` inside `terms` when you create a user credit balance, and read them from `terms` in responses.
2. Use `terms.duration` instead of `details.term`.
3. When you update a user credit balance with `PATCH`, use `terms.interest_rate`, `terms.effective_interest_rate`, and `past_due.days`.

### **Who This Affects**

Partners who started building against the User Credit Balance API from the preview docs.

**Nov 17, 2026**

## User Credit Balance Status Endpoints Return 422 When Nothing Changes

### **Why We Made This Change**

A `200` from an action endpoint used to mean either "the status changed" or "it was already in that status", so you had to compare the response with what you knew to tell whether your call did anything. The API is in preview, so this change ships without a new API version.

### **What Changed**

| Before | After |
| - | - |
| Calling activate, deactivate, close, or stop\_reporting on a user credit balance already in the target status, with a new `Idempotency-Key`, returns `200` with the user credit balance unchanged | The same call returns `422 object_state_mismatched` with `errors[].code` `object_status_unchanged`. Nothing changes |

A retry with the same `Idempotency-Key` still returns the original response. A `200` now always means the status changed.

### **What You Need To Do**

If your code treats a repeated status call as success, handle `object_status_unchanged` the same way. It means the user credit balance is already in the status you asked for.

### **Who This Affects**

Partners who started building against the User Credit Balance API from the preview docs.

**Nov 13, 2026**

## User Credit Balance Field and Value Changes

### **Why We Made This Change**

An API standards review found three names and formats in the User Credit Balance API that didn't match Lead's API standards. The API is in preview, so these changes ship without a new API version.

### **What Changed**

| Before | After |
| - | - |
| `interest.effective_apr` has 3 decimals, for example `10.250` | `interest.effective_apr` has 6 decimals, for example `10.250000`, the same as `rate` and `effective_rate` |
| `status_reason` value `client_closed` | `status_reason` value `partner_closed` |
| `details.repayment_details` | `details.repayment` |

### **What You Need To Do**

1. Send `interest.effective_apr` with exactly 6 decimals when you create a user credit balance. If your code reads or compares this value, expect 6 decimals in responses.
2. Send `partner_closed` instead of `client_closed` as the `status_reason` when you close a user credit balance. If your code reads `status_reason`, handle `partner_closed`.
3. Use `details.repayment` instead of `details.repayment_details` when you create, update, or read a user credit balance.

### **Who This Affects**

Partners who started building against the User Credit Balance API from the preview docs.
