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

# User Credit Balances: The Loan or Line of Credit You Report

> What a user credit balance is, how it relates to user accounts, user credit transactions, fundings, and receivables, and what you can do with the User Credit Balances API.

A user credit balance is the loan or line of credit you extend to one of your customers. It records the product's terms at creation and the position you report as your customer draws, accrues, and repays. You create user credit balances, update their terms, and manage their status through the User Credit Balances API.

You are the ledger of record. A user credit balance is Lead's copy of what your ledger shows, so Lead expects you to report every change to it until it reaches a closed state.

A user credit balance is not a user account. The user account holds who the customer is and the compliance data Lead needs. The user credit balance sits beneath the user account and reflects the amount of credit extended (i.e. amount owed) at any given point in time. One user account can hold several user credit balances, for example a term loan and a line of credit.

The creation of a user credit balance for your end-user first happens in your system, and the user credit balance record is how you provide Lead visibility into the balance you are tracking in your system as it is updated. See [Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting).

A user credit balance is also not a core balance. Core balances are the positions in your program's bank accounts at Lead, such as your FBO and operating accounts, and are documented under [Core Balance](/products/core-balance/overview).

<Note>
  The User Credit Balances API is currently in preview with a planned beta release in December 2026. Preview APIs are not yet available in sandbox or production and can change before beta. Use these pages to plan an integration, not to build one. Once released in beta, it will be available to all partners in sandbox, and in production for select programs. Beta APIs may change without a version increment, and changes will be announced in advance. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility).
</Note>

## Where it fits in onboarding

Create a user credit balance after its user account exists and before any money moves.

<Steps>
  <Step title="Entity API">
    Create an entity for each account holder, authorized signer, and authorized user.
  </Step>

  <Step title="Applications API">
    For underwritten credit products only. Report the final underwriting decision.
  </Step>

  <Step title="User Accounts API">
    Create the user account with the `credit_with_underwriting` or `credit_without_underwriting` feature.
  </Step>

  <Step title="User Credit Balances API">
    Create the user credit balance under the user account.
  </Step>

  <Step title="Funding API">
    Request a funding against the user credit balance to disburse to your customer (if your program supports lending; credit cards do not require use of this API).
  </Step>

  <Step title="User Credit Transactions API">
    Report every disbursement (if not through Funding API), accrual, fee, payment, and adjustment on the user credit balance.
  </Step>
</Steps>

When you create a user credit balance, Lead validates it against its parent user account. Lead rejects the request if the user account:

* Does not exist.
* Is not `active`.
* Has neither the `credit_with_underwriting` nor the `credit_without_underwriting` feature.

## Two structures

Every user credit balance has a `details.structure` that you set on create and cannot change:

* **`non_revolving`.** A term loan or buy now, pay later loan. The principal is fixed, and repayments do not restore available credit. Open one user credit balance per loan.
* **`revolving`.** A line of credit or credit card. The user credit balance stays open across many draws and repayments, and repayments restore available credit.

The structure sets which terms are required. [The User Credit Balance Object](/v2/products/user-credit-balance/user-credit-balance-object#the-details-block) page lists them.

## How the position updates

You never set amounts on a user credit balance directly. You post user credit transactions, and Lead applies each one to the user credit balance's `amount`, `amount_breakdown`, the `rewards` subobject, the `dispute` subobject, and the `charge_off` subobject.

Lead applies user credit transactions asynchronously. A `GET` request right after you post a user credit transaction can return the position from before that user credit transaction.

<Warning>
  Do not use the user credit balance to authorize spending. Your ledger stays the source of truth.
</Warning>

The `past_due` subobject is the exception. No user credit transaction moves it, so you report it with `PATCH`.

## How user credit balances relate to the rest of the model

* **User accounts.** Every user credit balance references a `user_account_id`. Create the user account first.
* **User credit transactions.** Every user credit transaction references the `user_credit_balance_id` it affects.
* **Fundings.** A funding draws against a user credit balance. On a `non_revolving` user credit balance, the total principal across fundings cannot exceed `details.max_funding_amount`.
* **Receivables.** Lead tracks the credit it holds on a user credit balance as a receivable. Receivable sales move that receivable to a buyer.
* **User deposit balances (coming soon).** A user account can also hold user deposit balances. They are separate objects with their own lifecycle.

## What you can do

* `POST /v2/user_accounts/{user_account_id}/user_credit_balances`: Create a user credit balance.
* `GET /v2/user_credit_balances/{id}`: Retrieve a user credit balance.
* `GET /v2/user_credit_balances`: List your user credit balances. See [Listing user credit balances](#listing-user-credit-balances).
* `PATCH /v2/user_credit_balances/{id}`: Update the terms and the past-due position you are allowed to change.
* `POST /v2/user_credit_balances/{id}/activate`: Move an `inactive` user credit balance to `active`.
* `POST /v2/user_credit_balances/{id}/deactivate`: Move an `active` user credit balance to `inactive`.
* `POST /v2/user_credit_balances/{id}/close`: Close the user credit balance.
* `POST /v2/user_credit_balances/{id}/stop_reporting`: Stop reporting on the user credit balance.

### Listing user credit balances

`GET /v2/user_credit_balances` returns your user credit balances with cursor pagination. Filter with these query parameters:

| Parameter | Type | Description |
| :- | :- | :- |
| `user_account_id` | string | Return only user credit balances under this user account. |
| `status` | enum | `active`, `inactive`, `closed`, or `reporting_stopped`. |
| `created_at[after]`, `created_at[on_or_after]`, `created_at[before]`, `created_at[on_or_before]` | timestamp | Return only user credit balances created in this range. RFC 3339. |
| `limit` | integer | The maximum number of user credit balances to return. |
| `starting_after` | string | A `user_credit_balance_` ID. Returns the page after this user credit balance. |
| `ending_before` | string | A `user_credit_balance_` ID. Returns the page before this user credit balance. |

### Authentication

* **`user_credit_balance/read_write`** for create, update, and the status endpoints. Also grants read access.
* **`user_credit_balance/read`** for the `GET` endpoints only. Use it when your integration only needs to read user credit balances.

## What you cannot do

* **Change amounts with `PATCH`.** Post a user credit transaction instead. `past_due` is the only position you set with `PATCH`.
* **Change the structure or the core terms.** `name`, `currency_code`, `details.structure`, `details.max_funding_amount`, `details.expected_finance_charge_amount`, and `interest.effective_apr` are set at creation.
* **Change status with `PATCH`.** Use the activate, deactivate, close, and stop\_reporting endpoints. See [User Credit Balance Statuses](/v2/products/user-credit-balance/statuses).
* **Mix old and new objects.** User credit balances are designed to be adopted together with user accounts and user credit transactions. Your Lead team will coordinate your move.
* **Subscribe to webhooks.** All status changes are yours, so Lead emits no events for them.

## In this section

* [The User Credit Balance Object](/v2/products/user-credit-balance/user-credit-balance-object)
* [User Credit Balance Statuses](/v2/products/user-credit-balance/statuses)


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