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

# The User Credit Balance Object

> Field-level reference for the User Credit Balance object, including the two structures, interest, the position blocks, create and update rules, and the mapping from the Subledger Balance API.

A user credit balance is the loan or line of credit you extend to one of your customers. You create one with `POST /v2/user_accounts/{user_account_id}/user_credit_balances` and read it with `GET /v2/user_credit_balances/{id}`.

```json theme={null}
{
  "id": "user_credit_balance_2xYv7Pm4Kq8RtW3nZ6bCdE1fG5h",
  "user_account_id": "user_account_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f",
  "name": "Personal Loan - Home Improvement",
  "status": "active",
  "status_reason": "active",
  "currency_code": "USD",
  "amount": 894400,
  "amount_in_usd": 894400,
  "amount_breakdown": {
    "principal": 500000,
    "interest": 252200,
    "fees": 142200
  },
  "rewards": {
    "amount": 0,
    "unit": "points"
  },
  "dispute": {
    "amount": 0,
    "amount_breakdown": { "principal": 0, "interest": 0, "fees": 0 }
  },
  "charge_off": {
    "amount": 0,
    "amount_breakdown": { "principal": 0, "interest": 0, "fees": 0 }
  },
  "past_due": {
    "amount": 0,
    "past_due_days": 0,
    "amount_breakdown": { "principal": 0, "interest": 0, "fees": 0 }
  },
  "interest": {
    "rate": "9.990000",
    "effective_rate": "9.500000",
    "effective_apr": "10.250"
  },
  "autopay_method": "ach",
  "details": {
    "structure": "non_revolving",
    "expected_maturity_date": "2028-09-01",
    "max_funding_amount": 1000000,
    "term": { "length": 24, "unit": "months" },
    "expected_finance_charge_amount": 0,
    "repayment_details": {
      "expected_payment_frequency": "monthly",
      "expected_number_of_payments": 24,
      "expected_first_payment_date": "2026-11-01",
      "expected_first_payment_amount": 37267,
      "expected_payment_amount": 37267,
      "expected_last_payment_date": "2028-09-01",
      "expected_last_payment_amount": 37267
    }
  },
  "metadata": {},
  "created_at": "2026-10-01T14:00:00Z",
  "updated_at": "2026-10-01T14:00:00Z"
}
```

A `revolving` user credit balance returns the same shape. Its `details` holds only `structure` and, if you sent it, `repayment_details`.

## Fields

| Field | Type | Description |
| :- | :- | :- |
| `id` | string | Unique identifier, prefixed `user_credit_balance_`. |
| `user_account_id` | string | The parent user account. Set from the create path. |
| `name` | string | The product name you offer the customer, for example "Personal Loan - Home Improvement". At most 64 characters. Cannot be changed. |
| `status` | enum | `active`, `inactive`, `closed`, or `reporting_stopped`. See [User Credit Balance Statuses](/v2/products/user-credit-balance/statuses). |
| `status_reason` | enum | Why the user credit balance is in its current status. See [Status reasons](/v2/products/user-credit-balance/statuses#status-reasons) on User Credit Balance Statuses. |
| `currency_code` | string | ISO 4217 currency code. `USD` only today. Cannot be changed. |
| `amount` | integer | The outstanding balance in minor units: the sum of `amount_breakdown`. Lead maintains it from your user credit transactions. |
| `amount_in_usd` | integer | `amount` converted to USD, in minor units. Equal to `amount` while `currency_code` is `USD`. |
| `amount_breakdown` | object | The outstanding principal, interest, and fees, in minor units. See [The position blocks](#the-position-blocks). |
| `rewards` | object | The rewards balance, if your product carries rewards. See [The position blocks](#the-position-blocks). |
| `dispute` | object | The amount currently in dispute. See [The position blocks](#the-position-blocks). |
| `charge_off` | object | The amount charged off. See [The position blocks](#the-position-blocks). |
| `past_due` | object | The amount currently past due. You set it with `PATCH`. See [The position blocks](#the-position-blocks). |
| `interest` | object | The rates on the user credit balance. See [The interest block](#the-interest-block). |
| `autopay_method` | enum | How the customer repays automatically: `ach`, `debit_card`, `wire`, `virtual_wallet`, `credit_card`, or `none`. |
| `details` | object | The structure and terms. See [The details block](#the-details-block). |
| `metadata` | object | String key-value pairs for your own use. Lead does not read them. |
| `created_at` | timestamp | RFC 3339, UTC. |
| `updated_at` | timestamp | RFC 3339, UTC. |
| `closed_at` | timestamp | When the user credit balance was closed. Set by Lead when you call `/close`. Omitted until then. |

## The position blocks

All amounts are signed integers in minor units. `1500` is \$15.00.

Lead maintains `amount_breakdown`, `rewards`, `dispute`, and `charge_off` from the user credit transactions you post. You maintain `past_due` with `PATCH`. [The User Credit Transaction Object](/v2/products/user-credit-transaction/user-credit-transaction-object#types) page lists which user credit transaction types move each block.

### amount\_breakdown

| Field | Type | Description |
| :- | :- | :- |
| `principal` | integer | Outstanding principal. |
| `interest` | integer | Outstanding interest. |
| `fees` | integer | Outstanding fees. |

### rewards

| Field | Type | Description |
| :- | :- | :- |
| `amount` | integer | The rewards balance, in minor units or points. Omitted until your first rewards user credit transaction sets it. |
| `unit` | enum | `USD` or `points`. Omitted until your first rewards user credit transaction sets it. |

### dispute

| Field | Type | Description |
| :- | :- | :- |
| `amount` | integer | The total in dispute. |
| `amount_breakdown` | object | The same total split into `principal`, `interest`, and `fees`. |

### charge\_off

| Field | Type | Description |
| :- | :- | :- |
| `amount` | integer | The total charged off. |
| `amount_breakdown` | object | The same total split into `principal`, `interest`, and `fees`. |

### past\_due

| Field | Type | Description |
| :- | :- | :- |
| `amount` | integer | The total past due. |
| `past_due_days` | integer | Total days past due. |
| `amount_breakdown` | object | The same total split into `principal`, `interest`, and `fees`. |

## The interest block

Send all three fields on create. Rates are decimal strings.

| Field | Type | Description |
| :- | :- | :- |
| `rate` | string | The contractual annual interest rate on outstanding principal, before compounding and fees. Exactly 6 decimals, for example `9.990000`. |
| `effective_rate` | string | The true annualized rate the user credit balance accrues at, including compounding. Exactly 6 decimals. |
| `effective_apr` | string | The APR you disclosed to the customer. Exactly 3 decimals, for example `10.250`. Cannot be changed. |

## The details block

| Field | Type | Description |
| :- | :- | :- |
| `structure` | enum | `non_revolving` or `revolving`. Required. Cannot be changed. |
| `expected_maturity_date` | date | `YYYY-MM-DD`. Required for `non_revolving`. Not allowed for `revolving`. |
| `max_funding_amount` | integer | The total you can fund, in minor units. For a term loan, the loan amount. Required for `non_revolving`. Not allowed for `revolving`. Cannot be changed. |
| `term` | object | The contractual term from origination to maturity: `length` (positive integer) and `unit` (`days`, `weeks`, `months`, or `years`). Required for `non_revolving`. Not allowed for `revolving`. |
| `expected_finance_charge_amount` | integer | The finance charge you disclosed, in minor units. Required for `non_revolving`. Not allowed for `revolving`. Cannot be changed. |
| `repayment_details` | object | The expected repayment schedule. Required for `non_revolving`. Optional for `revolving`. See below. |

<Warning>
  All five `non_revolving` fields are required, including `expected_finance_charge_amount`, which is easy to miss.
</Warning>

### details.repayment\_details

| Field | Type | Description |
| :- | :- | :- |
| `expected_payment_frequency` | enum | How often the customer is expected to pay: `business_daily`, `weekly`, `biweekly`, `semi_monthly`, `monthly`, `quarterly`, `semi_annually`, `annually`, `fixed_interval`, `maturity`, or `variable`. Required whenever you send `repayment_details`. |
| `expected_payment_frequency_interval_days` | integer | Days between payments, from 1 to 730. Required when `expected_payment_frequency` is `fixed_interval`. Not allowed otherwise. |
| `expected_number_of_payments` | integer | How many payments the customer makes on schedule. `non_revolving` only. |
| `expected_first_payment_date` | date | `YYYY-MM-DD`. If there is only one payment, use this field. `non_revolving` only. |
| `expected_first_payment_amount` | integer | Minor units. `non_revolving` only. |
| `expected_payment_amount` | integer | The amount of each regular payment, in minor units. `non_revolving` only. |
| `expected_last_payment_date` | date | `YYYY-MM-DD`. `non_revolving` only. |
| `expected_last_payment_amount` | integer | Minor units. `non_revolving` only. |

## Create and update

`POST /v2/user_accounts/{user_account_id}/user_credit_balances` requires an `Idempotency-Key` header. The request body takes these fields from the object: `name`, `currency_code`, `interest`, `autopay_method`, `details`, and `metadata`. Leave out everything else. Lead sets it, and rejects a request that sends it.

* Lead validates the request against the parent user account in the path. The user account must exist, be `active`, and have the `credit_with_underwriting` or `credit_without_underwriting` feature. If it is not `active` or lacks a credit feature, Lead returns a `422` with `operation_not_allowed`.
* `name`, `currency_code`, all three `interest` fields, `autopay_method`, and `details.structure` are always required.
* The `non_revolving` fields in [the details block](#the-details-block) are required for `non_revolving` and rejected for `revolving`.
* New user credit balances start in `active` with all amounts at zero.
* Reusing an `Idempotency-Key` with the same body returns the original user credit balance. Reusing it with a different body returns a `422` with `idempotency_request_inconsistent`.

`PATCH /v2/user_credit_balances/{id}` changes only the fields you send. `Idempotency-Key` is required on create and required on `PATCH` and the status endpoints. See [Idempotency](/api-reference/using-the-api/idempotency). You can change:

* `autopay_method` and `metadata`. Send `"metadata": null` to clear it.
* `past_due` and every field inside it.
* `interest.rate` and `interest.effective_rate`.
* `details.repayment_details`, for any structure.
* `details.expected_maturity_date` and `details.term`, for `non_revolving` only.

`PATCH` has these limits:

* You cannot change amounts other than `past_due`. Post a user credit transaction instead.
* You cannot change `name`, `currency_code`, `interest.effective_apr`, `details.structure`, `details.max_funding_amount`, or `details.expected_finance_charge_amount`.
* You cannot change `status`. Use the [status endpoints](/v2/products/user-credit-balance/statuses#transitions).
* You cannot update a `closed` or `reporting_stopped` user credit balance. Lead returns a `422` with `operation_not_allowed`. You can still update an `inactive` one.
* If another request changed the user credit balance after yours was received, Lead returns a `409` with `object_modified_concurrently`. Retrieve the user credit balance and retry.

## Coming from the Subledger Balance API

Most terms carry over. These are the fields that differ:

| Subledger Balance API | User Credit Balances API | What changed |
| :- | :- | :- |
| `id` (`subledger_balance_…`) | `id` (`user_credit_balance_…`) | New prefix. |
| `account_id` (request body) | `user_account_id` (path) | The parent is now a user account, set in the create path. |
| `client_subledger_balance_name` | `name` | Renamed. |
| `type` | — | Removed. Every user credit balance is credit. |
| `client_settlement_bank_account_id` | — | Removed. |
| `details.autopay_method` | `autopay_method` | Moved to the top level. |
| `details.is_interest_based` | — | Removed. `interest.rate` is always required. |
| `details.interest_rate` | `interest.rate` | Moved. |
| `details.effective_interest_rate` | `interest.effective_rate` | Moved and renamed. |
| `details.effective_apr` | `interest.effective_apr` | Moved. |
| `details.term.value` | `details.term.length` | Renamed. |
| `details.repayment_details` (array) | `details.repayment_details` (object) | Now a single object. |
| `details.balances.core.amount`, `amount_in_usd` | `amount`, `amount_in_usd` | Moved to the top level. |
| `details.balances.core.outstanding_principal`, `outstanding_interest`, `outstanding_fees` | `amount_breakdown.principal`, `interest`, `fees` | Moved and renamed. |
| `details.balances.rewards`, `dispute`, `charge_off`, `past_due` | `rewards`, `dispute`, `charge_off`, `past_due` | Moved to the top level. Component amounts sit under `amount_breakdown`. |
| `receivable_transferred` status | `reporting_stopped` status | Renamed. See [User Credit Balance Statuses](/v2/products/user-credit-balance/statuses). |
| Daily Balance file | User credit transactions, plus `PATCH` for `past_due` | You report the position through the API instead of files. |

## Related

* [User Credit Balance Overview](/v2/products/user-credit-balance/overview)
* [User Credit Balance Statuses](/v2/products/user-credit-balance/statuses)
* [The User Account Object](/v2/products/user-accounts/user-account-object)
* [The User Credit Transaction Object](/v2/products/user-credit-transaction/user-credit-transaction-object)
* [The Funding Object](/v2/products/fundings/funding-object)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.