The Balance Object

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 before any money moves. It carries the product’s terms at creation and, once live, Lead’s view of the current position. Fundings draw against it; your daily Balance file reporting keeps its position current.

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.

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

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.

Structure-specific fields:

Field	Type	Description
`expected_maturity_date`	date	Expected maturity. Must not be in the past when a Funding 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 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).

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

{
  "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": {}
}

Banking Infrastructure

Lending & Receivables

Payment Rails

Customers & Accounts

Network Settlement

Creating a Balance

Two Structures

Rate and Servicing Fields (both structures)

The Live Position

Statuses

Example Balance Object

​Creating a Balance

​Two Structures

​Rate and Servicing Fields (both structures)

​The Live Position

​Statuses

​Example Balance Object

Creating a Balance

Two Structures

Rate and Servicing Fields (both structures)

The Live Position

Statuses

Example Balance Object