The User Credit Balance Object

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

{
  "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.
`status_reason`	enum	Why the user credit balance is in its current status. See 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.
`rewards`	object	The rewards balance, if your product carries rewards. See The position blocks.
`dispute`	object	The amount currently in dispute. See The position blocks.
`charge_off`	object	The amount charged off. See The position blocks.
`past_due`	object	The amount currently past due. You set it with `PATCH`. See The position blocks.
`interest`	object	The rates on the user credit balance. See 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.
`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 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.

All five non_revolving fields are required, including expected_finance_charge_amount, which is easy to miss.

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 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. 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.
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.
Daily Balance file	User credit transactions, plus `PATCH` for `past_due`	You report the position through the API instead of files.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

The position blocks

amount_breakdown

rewards

dispute

charge_off

past_due

The interest block

The details block

details.repayment_details

Create and update

Coming from the Subledger Balance API

​Fields

​The position blocks

​amount_breakdown

​rewards

​dispute

​charge_off

​past_due

​The interest block

​The details block

​details.repayment_details

​Create and update

​Coming from the Subledger Balance API

​Related

Fields

The position blocks

amount_breakdown

rewards

dispute

charge_off

past_due

The interest block

The details block

details.repayment_details

Create and update

Coming from the Subledger Balance API

Related