> ## 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 Balance Object

> Field-level reference for the Subledger Balance — the loan or line of credit itself: creation requirements, non-revolving vs. revolving structures, rate fields, and the live position Lead maintains.

A Balance is the loan or line of credit itself — one Balance per term loan, line of credit, or overdraft product, with `type: credit`, created through the [Subledger Balance API](/api-reference/endpoint/subledger-balance/create-a-subledger-balance) before any money moves. It carries the product's terms at creation and, once live, Lead's view of the current position. [Fundings](/products/lending/funding-object) draw against it; your daily [Balance file reporting](/products/balances-and-transactions/overview) keeps its position current.

<Note>
  **Naming.** The API object is the **Subledger Balance** (`subledger_balance_*` IDs); in concept pages we say Balance. Future versions will standardize the name to Balance. Use the `subledger_balance_*` ID as the `balance_id` when reporting on this object in the daily Balance file.
</Note>

## Creating a Balance

`POST /v0/subledger_balances` with a required `Idempotency-Key` header (5–255 characters). The newly created Balance is `active` with `status_reason: active`.

| **Field**                           | **Type**     | **Required** | **Description**                                                                                                                                                                        |
| :---------------------------------- | :----------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_id`                        | string       | Yes          | The parent [Account](/products/accounts/overview). Must be in `active` or `inactive` status, and if the account declares `capabilities`, they must support the requested balance type. |
| `client_subledger_balance_name`     | string (≤64) | Yes          | The product name offered to the end user (e.g., "Personal Loan — Home Improvement", "BNPL loan").                                                                                      |
| `currency_code`                     | string       | Yes          | ISO 4217. `USD` only today.                                                                                                                                                            |
| `type`                              | enum         | Yes          | `credit` is the only value on create. (The response enum also includes `deposit`, reserved for future use.)                                                                            |
| `details`                           | object       | Yes          | The structure and terms — see below. `details.structure` is required.                                                                                                                  |
| `client_settlement_bank_account_id` | string       | No           | The underlying settlement bank account where funds for this Balance are held. Only applicable for certain use cases.                                                                   |
| `metadata`                          | object       | No           | Arbitrary key-value pairs.                                                                                                                                                             |

## Two Structures

`details.structure` declares how the credit behaves, and it changes what's required:

|                        | **`non_revolving`** (term loan, BNPL)                                                                                 | **`revolving`** (line of credit, credit card)           |
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------ |
| Behavior               | Fixed principal; repayments do not restore available credit                                                           | Subject to a limit; repayments restore available credit |
| Lifecycle              | A new Balance per loan, closed at terminal status                                                                     | One Balance stays open across many draws and repayments |
| **Required on create** | `expected_maturity_date` · `repayment_details` · `max_funding_amount` · `term` · **`expected_finance_charge_amount`** | `repayment_details` only                                |

<Warning>
  All five non-revolving fields are required — including `expected_finance_charge_amount` (minor units), which is easy to miss. Omitting any returns a 422 with the offending parameter named in `invalid_parameters`.
</Warning>

**Structure-specific fields:**

| **Field**                        | **Type** | **Description**                                                                                                                                                              |
| :------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expected_maturity_date`         | date     | Expected maturity. Must not be in the past when a [Funding](/products/lending/funding-object) is created against this Balance.                                               |
| `max_funding_amount`             | integer  | Maximum cumulative funding, minor units — for a term loan, the total loan amount. Cumulative principal across Fundings in `posted` or `processing` status cannot exceed it.  |
| `term`                           | object   | `{ value, unit }` where `unit` ∈ `days` / `weeks` / `months` / `years` — the contractual term from origination to expected maturity.                                         |
| `expected_finance_charge_amount` | integer  | The expected finance charge, minor units.                                                                                                                                    |
| `repayment_details`              | array    | The expected repayment schedule — see the [reference](api-reference/endpoint/subledger-balance/create-a-subledger-balance#body-details-one-of-0-repayment-details) for more. |

## Rate and Servicing Fields (both structures)

| **Field**                 | **Type** | **Description**                                                                                                                                                                        |
| :------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autopay_method`          | enum     | `ach`, `debit_card`, `wire`, `virtual_wallet`, `credit_card`, or `none`. Required for `credit`.                                                                                        |
| `is_interest_based`       | boolean  | Whether the Balance accrues interest. Required for `credit`.                                                                                                                           |
| `interest_rate`           | string   | The contractual (nominal) annual rate on outstanding principal, ignoring compounding and fees. **Required when `is_interest_based` is `true`.** Exactly 6 decimals (e.g., `9.990000`). |
| `effective_apr`           | string   | The APR as disclosed to the borrower. Required for `credit`. Exactly 3 decimals (e.g., `10.250`).                                                                                      |
| `effective_interest_rate` | string   | The true annualized cost of borrowing including compounding. Required for `credit`. Exactly 6 decimals (e.g., `9.500000`).                                                             |
| `balances.rewards.unit`   | enum     | `usd` or `points`, if the product carries rewards.                                                                                                                                     |

## The Live Position

The Balance response carries a `balances` object — Lead's current view of the position, maintained from your daily reporting:

| **Sub-object** | **Fields**                                                                                                        |
| :------------- | :---------------------------------------------------------------------------------------------------------------- |
| `core`         | `amount` (+ `amount_in_usd`), decomposed into `outstanding_principal`, `outstanding_interest`, `outstanding_fees` |
| `rewards`      | `amount`, `unit` (`usd`/`points`)                                                                                 |
| `dispute`      | `amount` + `principal`/`interest`/`fees` under dispute                                                            |
| `charge_off`   | `amount` + charged-off `principal`/`interest`/`fees`                                                              |
| `past_due`     | `amount`, `past_due_days`, + past-due `principal`/`interest`/`fees`                                               |

These are the same components your daily files must reconcile — `core.amount` must equal the sum of its three components, and each day's position must equal yesterday's plus the day's transactions ([Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation)).

## Statuses

| **Status** | **Meaning**                                                     |
| :--------- | :-------------------------------------------------------------- |
| `active`   | Live; Fundings may be created against it (default on creation). |
| `inactive` | Temporarily deactivated.                                        |
| `closed`   | Terminal.                                                       |

Statuses are yours to report and maintain — see [Balance Statuses](/products/balances-and-transactions/balance-statuses) for the full lifecycle. A Balance cannot be reported into a terminal status while any Funding against it is still `processing` (`balance_cannot_be_terminal_with_processing_funding`).

## Example Balance Object

```json theme={null}
{
  "id": "subledger_balance_k8L2n9QpW3xR5vT7mZ4jS1bA6cG",
  "account_id": "account_v9K4p2M7nL1wQ8xR5zB6tY3jH0gA",
  "client_subledger_balance_name": "Personal Loan - Home Improvement",
  "currency_code": "USD",
  "created_at": "2025-09-02T11:01:36Z",
  "updated_at": "2025-09-02T11:05:00Z",
  "status": "active",
  "status_reason": "active",
  "type": "credit",
  "details": {
    "structure": "non_revolving",
    "expected_maturity_date": "2027-09-01",
    "max_funding_amount": 10000000,
    "term": { "value": 24, "unit": "months" },
    "expected_finance_charge_amount": 100000,
    "repayment_details": [
      {
        "expected_payment_frequency": "monthly",
        "expected_number_of_payments": 24,
        "expected_first_payment_date": "2025-10-01",
        "expected_payment_amount": 4167,
        "expected_last_payment_date": "2027-09-01",
        "expected_last_payment_amount": 4167
      }
    ],
    "autopay_method": "ach",
    "is_interest_based": true,
    "interest_rate": "9.990000",
    "effective_apr": "10.250",
    "effective_interest_rate": "9.500000",
    "balances": {
      "core": {
        "amount": 8944,
        "amount_in_usd": 8944,
        "outstanding_principal": 5000,
        "outstanding_interest": 2522,
        "outstanding_fees": 1422
      },
      "past_due": { "amount": 15, "past_due_days": 15, "principal": 15, "interest": 0, "fees": 0 }
    }
  },
  "metadata": {}
}
```