---
title: "Create a Subledger Balance"
method: POST
path: "/v0/subledger_balances"
tags: ["Subledger Balances"]
---

# Create a Subledger Balance

`POST /v0/subledger_balances`

Create a Subledger Balance object. The newly created Subledger Balance will have a `status` of `active` and a `status_reason` of `active`, and a unique `id` with prefix `subledger_balance_` will be auto-generated.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateSubledgerBalanceRequest
  - `account_id` string, required — Unique identifier for the Account object that the Subledger Balance belongs to. Must reference an Account object in a permitted status (`active` or `inactive`). If the Account includes a `capabilities` array, the requested Subledger Balance `type` must be supported.
  - `client_subledger_balance_name` string, required — A name for the product or Subledger Balance being offered to the end-user (e.g., Rainy Day Fund, BNPL loan).
  - `client_settlement_bank_account_id` string — ID of the underlying settlement bank account where funds for the Subledger Balance are held. Only applicable for certain use cases.
  - `currency_code` 'USD', required — A three-letter currency code as defined in ISO 4217.
  - `type` 'credit', required — The type of Subledger Balance.
  - `metadata` Metadata — A set of key-value pairs that can be used to store additional information related to this object.
  - `details` union, required
    - object
      - `structure` 'non_revolving' | 'revolving', required — The structure of the credit product.
      - `balances` object
        - `rewards` object
          - `unit` 'usd' | 'points', required
      - `autopay_method` 'ach' | 'debit_card' | 'wire' | 'virtual_wallet' | 'credit_card' | 'none' — The autopay method. Required if `type` is `credit`.
      - `is_interest_based` boolean, nullable — Indicates whether the Subledger Balance is interest-based. Required if `type` is `credit`.
      - `effective_apr` string — The APR as disclosed to the borrower. Required if `type` is `credit`. Must have exactly 3 decimal places (e.g., `10.250`).
      - `effective_interest_rate` string — The true annualized cost of borrowing, taking into account the interest rate and impact of compounding. Required if `type` is `credit`. Must have exactly 6 decimal places (e.g., `9.500000`).
      - `interest_rate` string — For deposit products, the annualized interest rate offered to customers on this Subledger Balance. For credit products, the contractual annual rate of interest charged on the loan’s outstanding principal, without taking into account compounding frequency or additional fees. Also known as the stated interest rate or nominal interest rate. Required when `is_interest_based` is `true`. Must have exactly 6 decimal places (e.g., `9.990000`).
      - `expected_maturity_date` string, date, required — The expected maturity date of the loan. Must not be in the past when creating a Funding against this Subledger Balance.
      - `repayment_details` RepaymentDetails[], required
        - `expected_payment_frequency` 'business_daily' | 'weekly' | 'biweekly' | 'semi_monthly' | 'monthly' | 'quarterly' | 'semi_annually' | 'annually' | 'fixed_interval' | 'maturity' | 'variable', required — The expected frequency with which customer payments will occur. **Calendar-based frequencies:** - `weekly` — Once per week. - `biweekly` — Once every two weeks (26 payments/year). - `semi_monthly` — Twice per month on fixed calendar days (24 payments/year). - `monthly` — Once per calendar month. - `quarterly` — Once every calendar quarter (4 payments/year). - `semi_annually` — Once every 6 months (2 payments/year). - `annually` — Once per calendar year. - `business_daily` — Once per business day. **Fixed-interval frequencies:** - `fixed_interval` — Payments occur after a fixed number of elapsed days rather than on calendar-based dates. When using this value, `expected_payment_frequency_interval_days` is required. **Non-time-based frequencies:** - `maturity` — A single payment at loan maturity. - `variable` — Repayment does not follow a predictable time-based cadence; instead, payments are event-driven (e.g., repayment occurs the next time funds enter the borrower's account).
        - `expected_payment_frequency_interval_days` integer — The number of days between expected customer payments when the repayment schedule follows a fixed interval. **Required** when `expected_payment_frequency` is `fixed_interval`. **Must not be present** when `expected_payment_frequency` is any other value.
        - `expected_number_of_payments` integer — The expected number of payments if the customer pays according to the loan schedule.
        - `expected_first_payment_date` string, date — The expected date of the first customer repayment. If there is only one repayment please use this field.
        - `expected_first_payment_amount` integer — The expected amount of the first customer repayment expressed as an integer in minor units. If there is only one repayment please use this field.
        - `expected_last_payment_date` string, date — The expected date of the last customer repayment.
        - `expected_last_payment_amount` integer — The expected amount of the last customer repayment expressed as an integer in minor units.
        - `expected_payment_amount` integer — The expected payment amount in each repayment expressed as an integer in minor units.
      - `max_funding_amount` integer, required — The maximum funding amount as an integer in minor units. For a term loan, this would be equivalent to the total loan amount. Cumulative Funding requests against this Subledger Balance cannot exceed this amount.
      - `term` Term, required
        - `value` integer, required — The number of units in the contractual term length.
        - `unit` 'days' | 'weeks' | 'months' | 'years', required — The unit of the contractual term length. E.g., for a term loan, this represents the contractual loan term from the date of origination to the expected maturity date.
      - `expected_finance_charge_amount` integer, required — The expected finance charge amount expressed as an integer in minor units.
    - object
      - `structure` 'non_revolving' | 'revolving', required — The structure of the credit product.
      - `balances` object
        - `rewards` object
          - `unit` 'usd' | 'points', required
      - `autopay_method` 'ach' | 'debit_card' | 'wire' | 'virtual_wallet' | 'credit_card' | 'none' — The autopay method. Required if `type` is `credit`.
      - `is_interest_based` boolean, nullable — Indicates whether the Subledger Balance is interest-based. Required if `type` is `credit`.
      - `effective_apr` string — The APR as disclosed to the borrower. Required if `type` is `credit`. Must have exactly 3 decimal places (e.g., `10.250`).
      - `effective_interest_rate` string — The true annualized cost of borrowing, taking into account the interest rate and impact of compounding. Required if `type` is `credit`. Must have exactly 6 decimal places (e.g., `9.500000`).
      - `interest_rate` string — For deposit products, the annualized interest rate offered to customers on this Subledger Balance. For credit products, the contractual annual rate of interest charged on the loan’s outstanding principal, without taking into account compounding frequency or additional fees. Also known as the stated interest rate or nominal interest rate. Required when `is_interest_based` is `true`. Must have exactly 6 decimal places (e.g., `9.990000`).
      - `repayment_details` RevolvingRepaymentDetails[], required
        - `expected_payment_frequency` 'business_daily' | 'weekly' | 'biweekly' | 'semi_monthly' | 'monthly' | 'quarterly' | 'semi_annually' | 'annually' | 'fixed_interval' | 'maturity' | 'variable', required — The expected frequency with which customer payments will occur. **Calendar-based frequencies:** - `weekly` — Once per week. - `biweekly` — Once every two weeks (26 payments/year). - `semi_monthly` — Twice per month on fixed calendar days (24 payments/year). - `monthly` — Once per calendar month. - `quarterly` — Once every calendar quarter (4 payments/year). - `semi_annually` — Once every 6 months (2 payments/year). - `annually` — Once per calendar year. - `business_daily` — Once per business day. **Fixed-interval frequencies:** - `fixed_interval` — Payments occur after a fixed number of elapsed days rather than on calendar-based dates. When using this value, `expected_payment_frequency_interval_days` is required. **Non-time-based frequencies:** - `maturity` — A single payment at loan maturity. - `variable` — Repayment does not follow a predictable time-based cadence; instead, payments are event-driven (e.g., repayment occurs the next time funds enter the borrower's account).
        - `expected_payment_frequency_interval_days` integer — The number of days between expected customer payments when the repayment schedule follows a fixed interval. **Required** when `expected_payment_frequency` is `fixed_interval`. **Must not be present** when `expected_payment_frequency` is any other value.

## Response `200`

Subledger Balance created successfully

- SubledgerBalanceResponse
  - `account_id` string — Unique identifier for the account that the Subledger Balance belongs to.
  - `id` string — Lead-generated unique identifier for the Subledger Balance. This ID should subsequently be used when reporting on this object in the Balance file.
  - `client_subledger_balance_name` string — A name for the product or Subledger Balance being offered to the end-user (e.g., Rainy Day Fund, BNPL loan).
  - `client_settlement_bank_account_id` string — ID of the underlying settlement bank account where funds for the Subledger Balance are held. Only applicable for certain use cases.
  - `currency_code` 'USD' — A three-letter currency code as defined in ISO 4217.
  - `created_at` string, date-time — An ISO-8601 timestamp at which the Subledger Balance was created in Lead's system.
  - `updated_at` string, date-time — An ISO-8601 timestamp at which the Subledger Balance was last updated in Lead's system.
  - `status` 'active' | 'inactive' | 'closed' — Status of the Subledger Balance.
  - `status_reason` string — Reason associated with the status of the Subledger Balance.
  - `type` 'credit' | 'deposit' — The type of Subledger Balance.
  - `metadata` Metadata — A set of key-value pairs that can be used to store additional information related to this object.
  - `details` union
    - object
      - `structure` string, required
      - `balances` BalanceAmountsResponse
        - `core` CoreBalanceResponse
          - `amount` integer — The total balance amount as an integer in minor units.
          - `amount_in_usd` integer — The total balance amount in USD as an integer in minor units.
          - `outstanding_principal` integer — The outstanding principal amount as an integer in minor units.
          - `outstanding_interest` integer — The outstanding interest amount as an integer in minor units.
          - `outstanding_fees` integer — The outstanding fees amount as an integer in minor units.
        - `rewards` RewardsBalanceResponse
          - `amount` integer — The rewards balance amount as an integer in minor units.
          - `unit` 'usd' | 'points' — The unit of measurement for the rewards balance amount.
        - `dispute` DisputeBalanceResponse
          - `amount` integer — The total amount that is currently under dispute as an integer in minor units.
          - `principal` integer — The amount of principal that is currently under dispute as an integer in minor units
          - `interest` integer — The amount of interest that is currently under dispute as an integer in minor units
          - `fees` integer — The amount of fees that is currently under dispute as an integer in minor units
        - `charge_off` ChargeOffBalanceResponse
          - `amount` integer — The charged-off amount as an integer in minor units.
          - `principal` integer — The charged-off principal amount as an integer in minor units.
          - `interest` integer — The charged-off interest amount as an integer in minor units.
          - `fees` integer — The charged-off fees amount as an integer in minor units.
        - `past_due` PastDueBalanceResponse
          - `amount` integer — The total past due amount as an integer in minor units.
          - `past_due_days` integer — The number of days that the balance is past due.
          - `principal` integer — The past due principal amount as an integer in minor units.
          - `interest` integer — The past due interest amount as an integer in minor units.
          - `fees` integer — The past due fees amount as an integer in minor units.
      - `autopay_method` 'ach' | 'debit_card' | 'wire' | 'virtual_wallet' | 'credit_card' | 'none' — The autopay method. Required if `type` is `credit`.
      - `is_interest_based` boolean, nullable — Indicates whether the Subledger Balance is interest-based. Required if `type` is `credit`.
      - `effective_apr` string — The APR as disclosed to the borrower. Required if `type` is `credit`.
      - `effective_interest_rate` string — The true annualized cost of borrowing, taking into account the interest rate and impact of compounding. Required if `type` is `credit`.
      - `interest_rate` string — For deposit products, the annualized interest rate offered to customers on this Subledger Balance. For credit products, the contractual annual rate of interest charged on the loan’s outstanding principal, without taking into account compounding frequency or additional fees. Also known as the stated interest rate or nominal interest rate.
      - `expected_maturity_date` string, date — The expected maturity date of the loan.
      - `repayment_details` RepaymentDetailsResponse[]
        - `expected_payment_frequency` 'business_daily' | 'weekly' | 'biweekly' | 'semi_monthly' | 'monthly' | 'quarterly' | 'semi_annually' | 'annually' | 'fixed_interval' | 'maturity' | 'variable' — The expected frequency with which customer payments will occur. **Calendar-based frequencies:** - `weekly` — Once per week. - `biweekly` — Once every two weeks (26 payments/year). - `semi_monthly` — Twice per month on fixed calendar days (24 payments/year). - `monthly` — Once per calendar month. - `quarterly` — Once every calendar quarter (4 payments/year). - `semi_annually` — Once every 6 months (2 payments/year). - `annually` — Once per calendar year. - `business_daily` — Once per business day. **Fixed-interval frequencies:** - `fixed_interval` — Payments occur after a fixed number of elapsed days rather than on calendar-based dates. When using this value, `expected_payment_frequency_interval_days` is required. **Non-time-based frequencies:** - `maturity` — A single payment at loan maturity. - `variable` — Repayment does not follow a predictable time-based cadence; instead, payments are event-driven (e.g., repayment occurs the next time funds enter the borrower's account).
        - `expected_payment_frequency_interval_days` integer — The number of days between expected customer payments when the repayment schedule follows a fixed interval. Present when `expected_payment_frequency` is `fixed_interval`. Not present for any other frequency value.
        - `expected_number_of_payments` integer — The expected number of payments if the customer pays according to the loan schedule.
        - `expected_first_payment_date` string, date — The expected date of the first customer repayment. If there is only one repayment please use this field.
        - `expected_first_payment_amount` integer — The expected amount of the first customer repayment expressed as an integer in minor units. If there is only one repayment please use this field.
        - `expected_last_payment_date` string, date — The expected date of the last customer repayment.
        - `expected_last_payment_amount` integer — The expected amount of the last customer repayment expressed as an integer in minor units.
        - `expected_payment_amount` integer — The expected payment amount in each repayment expressed as an integer in minor units.
      - `max_funding_amount` integer — The maximum funding amount expressed as an integer in minor units. For a term loan, this would be equivalent to the total loan amount.
      - `term` TermResponse
        - `value` integer — The number of units in the contractual term length.
        - `unit` 'days' | 'weeks' | 'months' | 'years' — The unit of the contractual term length. E.g., for a term loan, this represents the contractual loan term from the date of origination to the expected maturity date.
      - `expected_finance_charge_amount` integer — The expected finance charge amount expressed as an integer in minor units.
    - object
      - `structure` string, required
      - `balances` BalanceAmountsResponse
        - `core` CoreBalanceResponse
          - `amount` integer — The total balance amount as an integer in minor units.
          - `amount_in_usd` integer — The total balance amount in USD as an integer in minor units.
          - `outstanding_principal` integer — The outstanding principal amount as an integer in minor units.
          - `outstanding_interest` integer — The outstanding interest amount as an integer in minor units.
          - `outstanding_fees` integer — The outstanding fees amount as an integer in minor units.
        - `rewards` RewardsBalanceResponse
          - `amount` integer — The rewards balance amount as an integer in minor units.
          - `unit` 'usd' | 'points' — The unit of measurement for the rewards balance amount.
        - `dispute` DisputeBalanceResponse
          - `amount` integer — The total amount that is currently under dispute as an integer in minor units.
          - `principal` integer — The amount of principal that is currently under dispute as an integer in minor units
          - `interest` integer — The amount of interest that is currently under dispute as an integer in minor units
          - `fees` integer — The amount of fees that is currently under dispute as an integer in minor units
        - `charge_off` ChargeOffBalanceResponse
          - `amount` integer — The charged-off amount as an integer in minor units.
          - `principal` integer — The charged-off principal amount as an integer in minor units.
          - `interest` integer — The charged-off interest amount as an integer in minor units.
          - `fees` integer — The charged-off fees amount as an integer in minor units.
        - `past_due` PastDueBalanceResponse
          - `amount` integer — The total past due amount as an integer in minor units.
          - `past_due_days` integer — The number of days that the balance is past due.
          - `principal` integer — The past due principal amount as an integer in minor units.
          - `interest` integer — The past due interest amount as an integer in minor units.
          - `fees` integer — The past due fees amount as an integer in minor units.
      - `autopay_method` 'ach' | 'debit_card' | 'wire' | 'virtual_wallet' | 'credit_card' | 'none' — The autopay method. Required if `type` is `credit`.
      - `is_interest_based` boolean, nullable — Indicates whether the Subledger Balance is interest-based. Required if `type` is `credit`.
      - `effective_apr` string — The APR as disclosed to the borrower. Required if `type` is `credit`.
      - `effective_interest_rate` string — The true annualized cost of borrowing, taking into account the interest rate and impact of compounding. Required if `type` is `credit`.
      - `interest_rate` string — For deposit products, the annualized interest rate offered to customers on this Subledger Balance. For credit products, the contractual annual rate of interest charged on the loan’s outstanding principal, without taking into account compounding frequency or additional fees. Also known as the stated interest rate or nominal interest rate.
      - `repayment_details` RevolvingRepaymentDetailsResponse[]
        - `expected_payment_frequency` 'business_daily' | 'weekly' | 'biweekly' | 'semi_monthly' | 'monthly' | 'quarterly' | 'semi_annually' | 'annually' | 'fixed_interval' | 'maturity' | 'variable' — The expected frequency with which customer payments will occur. **Calendar-based frequencies:** - `weekly` — Once per week. - `biweekly` — Once every two weeks (26 payments/year). - `semi_monthly` — Twice per month on fixed calendar days (24 payments/year). - `monthly` — Once per calendar month. - `quarterly` — Once every calendar quarter (4 payments/year). - `semi_annually` — Once every 6 months (2 payments/year). - `annually` — Once per calendar year. - `business_daily` — Once per business day. **Fixed-interval frequencies:** - `fixed_interval` — Payments occur after a fixed number of elapsed days rather than on calendar-based dates. When using this value, `expected_payment_frequency_interval_days` is required. **Non-time-based frequencies:** - `maturity` — A single payment at loan maturity. - `variable` — Repayment does not follow a predictable time-based cadence; instead, payments are event-driven (e.g., repayment occurs the next time funds enter the borrower's account).
        - `expected_payment_frequency_interval_days` integer — The number of days between expected customer payments when the repayment schedule follows a fixed interval. Present when `expected_payment_frequency` is `fixed_interval`. Not present for any other frequency value.

## Other responses

- `400` — Your request body did not parse.
- `401` — The token passed in is invalid.
- `403` — Token has insufficient permissions for this request.
- `422` — Your request parameters did not validate.
- `429` — You've reached the rate limit for this call.
- `500` — Server error. Please try your request again.

---

[API](https://skmtc.net/lead/apis/lead-bank.md) · [All operations](https://skmtc.net/lead/apis/lead-bank/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lead/lead-bank/revisions/25c2a92d55e2/schema)