---
title: "Create a Credit Balance"
method: POST
path: "/v2/user_accounts/{user_account_id}/user_credit_balances"
tags: ["User Credit Balance"]
---

# Create a Credit Balance

`POST /v2/user_accounts/{user_account_id}/user_credit_balances`

## Request

- Base URL: `https://api.sandbox.lead.bank`
- URL: `https://api.sandbox.lead.bank/v2/user_accounts/{user_account_id}/user_credit_balances`
- Auth: HTTP bearer

Create a User Credit Balance under an existing User Account. `user_account_id` comes from the URL path, not the request body. New User Credit Balances have `status: active`.

## Path parameters

- `user_account_id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateUserCreditBalanceRequest: Request body for creating a new User Credit Balance.
  - `name` string, required
  - `currency_code` 'USD', required: A three-letter currency code as defined in ISO 4217.
  - `interest` object, required
    - `rate` string, required: Decimal string with exactly 6 digits after the decimal point.
    - `effective_rate` string, required: Decimal string with exactly 6 digits after the decimal point.
    - `effective_apr` string, required: Decimal string with exactly 3 digits after the decimal point.
  - `autopay_method` 'ach' | 'debit_card' | 'wire' | 'virtual_wallet' | 'credit_card' | 'none', required
  - `details` union, required
    - CreateUserCreditBalanceRevolvingDetail
      - `structure` 'revolving', required
      - `repayment_details` CreateUserCreditBalanceRepaymentDetailsRevolving
        - `expected_payment_frequency` 'fixed_interval', required
        - `expected_payment_frequency_interval_days` integer, required
    - CreateUserCreditBalanceNonRevolvingDetail
      - `structure` 'non_revolving', required
      - `expected_maturity_date` string, date, required
      - `repayment_details` CreateUserCreditBalanceRepaymentDetailsNonRevolving, required
        - `expected_payment_frequency` 'fixed_interval', required
        - `expected_payment_frequency_interval_days` integer, required
        - `expected_number_of_payments` integer
        - `expected_first_payment_date` string, date
        - `expected_first_payment_amount` integer: Minor units.
        - `expected_last_payment_date` string, date
        - `expected_last_payment_amount` integer: Minor units.
        - `expected_payment_amount` integer: Minor units.
      - `max_funding_amount` integer, required: Minor units.
      - `term` object, required
        - `length` integer, required
        - `unit` 'days' | 'weeks' | 'months' | 'years', required
      - `expected_finance_charge_amount` integer, required: Minor units.
  - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object.

## Response `200`

Credit Balance created successfully

- UserCreditBalance: A user credit balance — a virtual end-customer credit position.
  - `id` string
  - `user_account_id` string: The parent User Account's ID.
  - `name` string: Human-readable name.
  - `status` 'active' | 'inactive' | 'closed' | 'reporting_stopped'
  - `status_reason` 'active' | 'frozen' | 'dormant' | 'other' | 'entity_closed' | 'client_closed' | 'paid_off' | 'charged_off' | 'canceled' | 'receivables_sold_to_partner' | 'data_not_available'
  - `currency_code` 'USD': A three-letter currency code as defined in ISO 4217.
  - `amount` integer: Signed, minor units.
  - `amount_in_usd` integer: Signed, minor units, in USD.
  - `amount_breakdown` UserCreditBalanceAmountBreakdown
    - `principal` integer: Principal portion, minor units.
    - `interest` integer: Interest portion, minor units.
    - `fees` integer: Fees portion, minor units.
  - `fees` UserCreditBalanceFees
    - `accrued` integer: Total fees accrued to date, minor units.
  - `rewards` UserCreditBalanceRewards
    - `amount` integer
    - `unit` 'USD' | 'points'
  - `dispute` UserCreditBalanceDispute
    - `amount` integer
    - `amount_breakdown` UserCreditBalanceAmountBreakdown
      - `principal` integer: Principal portion, minor units.
      - `interest` integer: Interest portion, minor units.
      - `fees` integer: Fees portion, minor units.
  - `charge_off` UserCreditBalanceChargeOff
    - `amount` integer
    - `amount_breakdown` UserCreditBalanceAmountBreakdown
      - `principal` integer: Principal portion, minor units.
      - `interest` integer: Interest portion, minor units.
      - `fees` integer: Fees portion, minor units.
  - `past_due` UserCreditBalancePastDue
    - `amount` integer
    - `past_due_days` integer
    - `amount_breakdown` UserCreditBalanceAmountBreakdown
      - `principal` integer: Principal portion, minor units.
      - `interest` integer: Interest portion, minor units.
      - `fees` integer: Fees portion, minor units.
  - `interest` UserCreditBalanceInterest
    - `rate` string: Decimal string with exactly 6 digits after the decimal point.
    - `effective_rate` string: Decimal string with exactly 6 digits after the decimal point.
    - `effective_apr` string: Decimal string with exactly 3 digits after the decimal point.
  - `autopay_method` 'ach' | 'debit_card' | 'wire' | 'virtual_wallet' | 'credit_card' | 'none'
  - `details` UserCreditBalanceDetails
    - `structure` 'revolving' | 'non_revolving'
    - `expected_maturity_date` string, date
    - `repayment_details` UserCreditBalanceRepaymentDetails
      - `expected_payment_frequency` 'business_daily' | 'weekly' | 'biweekly' | 'semi_monthly' | 'monthly' | 'quarterly' | 'semi_annually' | 'annually' | 'fixed_interval' | 'maturity' | 'variable'
      - `expected_payment_frequency_interval_days` integer
      - `expected_number_of_payments` integer
      - `expected_first_payment_date` string, date
      - `expected_first_payment_amount` integer: Minor units.
      - `expected_last_payment_date` string, date
      - `expected_last_payment_amount` integer: Minor units.
      - `expected_payment_amount` integer: Minor units.
    - `max_funding_amount` integer: Minor units.
    - `term` UserCreditBalanceDetailsTerm
      - `length` integer
      - `unit` 'days' | 'weeks' | 'months' | 'years'
    - `expected_finance_charge_amount` integer: Minor units.
  - `metadata` Metadata: A set of key-value pairs that can be used to store additional information related to this object.
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `closed_at` string, date-time, nullable

## Other responses

- `400`: The request could not be parsed, or a required header is missing.
- `403`: Rejected before the request reached the User Credit Balance API. `code` is one of: `authentication_missing` (the request has no credentials), `token_invalid` (the bearer token is expired, invalid, or does not grant the required scope), `source_ip_not_permitted` (the request came from an IP address that is not on your program's allowlist).
- `404`: The parent User Account ID passed in is not found.
- `409`: A concurrent request with the same `Idempotency-Key` is still in flight.
- `422`: Your request parameters did not validate.
- `429`: You've reached the rate limit for this call.
- `500`: Internal server error.
- `503`: The endpoint is temporarily disabled. Retry after the interval given in the `Retry-After` header.
- `504`: An upstream system did not respond in time. Retry with backoff, and with the same `Idempotency-Key` on a `POST` or `PATCH`.

## Changes

- **2026-11-03** `2c659854496e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/lead/apis/lead-bank/changes/v2/user_accounts/:user_account_id/user_credit_balances/post.md)

---

[API](https://skmtc.dev/lead/apis/lead-bank.md) - [All operations](https://skmtc.dev/lead/apis/lead-bank/llms.txt) - [OpenAPI document](https://skmtc.dev/lead/apis/lead-bank/revisions/2c659854496e?raw)