# Ledger account balances

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


## Credit Grants[](#credit-grants)

A credit grant is a quantified allocation of credits given to a subscription through a configured [item price](/docs/api/item_prices) or via the [allocate](/docs/api/ledger_operations/allocate) operation, consumed over time through ledger operations.

**Example**

A subscription receives a credit grant of 100 AI credits as a balance. As the customer uses AI features (e.g., Image Generation), the provisioned balance is consumed first. Once exhausted, further consumption is deducted from the overdraft balance until its limit is reached.

## The Ledger Account Balance object[](#the-ledger-account-balance-object)

The `ledger_account_balance` object is a real-time snapshot of credit grants for a single combination of subscription\_id, unit\_id and unit\_type.

The ledger tracks two balances:

-   [**provisioned\_balance**](#provisioned_balance): Reflects the credit grants given through the configured item price or allocate operations. These are prepaid credit grants for which the customer has already paid. Any ledger operation will prioritize consuming this balance first.
-   [**overdraft\_balance**](#overdraft_balance): Reflects the extra limit provided to a subscription in case it exhausts all credit grants before they are renewed or refreshed. Any ledger operation will consume this balance only when the provisioned balance has been exhausted.

**Note**

These two balances are always tracked together for a subscription with credit grants.

**Example**

A subscription has a credit grant of 100 AI credits, added to its provisioned balance. Once the provisioned balance is exhausted, further consumption is drawn from the overdraft balance up to its configured limit.

![AI Credits Balance Flow](/images/account_balance.png)

  

**Returned by**

-   [List ledger account balances](/docs/api/ledger_account_balances/list-ledger-account-balances) API.
-   Ledger [operations](/docs/api/ledger_operations) such as [allocate](/docs/api/ledger_operations/allocate), [capture](/docs/api/ledger_operations/capture), and [authorize](/docs/api/ledger_operations/authorize).

## Sample Ledger-account-balance

```json
{
  "ledger_account_balance": {
    "subscription_id": "1mGETgZVF2umUZq",
    "unit_id": "ai_credits",
    "unit_type": "credit_unit",
    "created_at": 1746723600,
    "modified_at": 1774978599,
    "resource_version": 1774978599000,
    "provisioned_balance": {
      "total_balance": "100.25",
      "usable_balance": "49.7975",
      "hold_amount": "50.4525"
    },
    "overdraft_balance": {
      "is_unlimited": false,
      "limit": "20",
      "total_balance": "20",
      "usable_balance": "20",
      "used_amount": "0",
      "hold_amount": "0"
    },
    "object": "ledger_account_balance"
  }
}
```

## Ledger account balances attributes

## Input Parameters

- `subscription_id` (required, string, max chars=50)
  A unique, immutable identifier for the [subscription](/docs/api/subscriptions/subscription-object#id) this account belongs to.

- `unit_id` (required, string, max chars=50)
  Identifier of the credit unit this account tracks. For example, a credit unit id such as `ai_credits`.

- `unit_type` (required, enumerated string)
  Type of unit used for this balance.
  Possible enum values:
    - `credit_unit`
      The unit represents a credit unit, the type used by credit grants.

- `created_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) indicating when this ledger account balance was first recorded.

- `modified_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (seconds) when the balance was last updated. For example, after [allocate](/docs/api/ledger_operations/allocate), [capture](/docs/api/ledger_operations/capture), or [authorize](/docs/api/ledger_operations/authorize).

- `resource_version` (optional, long)
  Version number of this resource. The `resource_version` is updated with a new timestamp for every change made to the resource.

- `provisioned_balance` (optional, provisioned_balance)
  Stores credit grants given through the configured item price. Used first before overdraft.
  - `total_balance` (required, string, max chars=36)
    Total granted credits remaining, including held amounts. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
    
    `total_balance = usable_balance + hold_amount`
    
    **Example:** If a subscription has a credit grant of `100` AI credits and `30` have been consumed, total\_balance is `70`.
  - `usable_balance` (required, string, max chars=36)
    Credits available for immediate use (excludes held amount). Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
    
    **Example:** If total\_balance is `70` and hold\_amount is `5`, usable\_balance is `65`.
  - `hold_amount` (required, string, max chars=36)
    Credits reserved for in-progress operations (e.g., authorize); not currently usable. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
    
    **Example:** If `10` AI credits are reserved for a pending operation, hold\_amount is `10` and usable\_balance is reduced accordingly.

- `overdraft_balance` (optional, overdraft_balance)
  Extra credit available after provisioned balance is exhausted.
  - `is_unlimited` (required, boolean, default=false)
    Whether overdraft has no limit (`true`) or is capped (`false`). When `true`, the `limit`, `total_balance`, `usable_balance`, and `hold_amount` fields are `null`.
  - `limit` (optional, string, max chars=36)
    Maximum overdraft allowed. Present only when [`overdraft_balance.is_unlimited`](#overdraft_balance_is_unlimited) is `false`. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `total_balance` (optional, string, max chars=36)
    Total granted credits remaining, including held amounts. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
    
    **Example:** If limit is `25` and used\_amount is `10`, the remaining overdraft capacity is `15`.
  - `usable_balance` (optional, string, max chars=36)
    Remaining overdraft available for use. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
    
    Usable Balance (Only if Capped): `limit - used_amount - hold_amount`.
  - `used_amount` (required, string, max chars=36)
    Credits already consumed from overdraft. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  - `hold_amount` (required, string, max chars=36)
    Overdraft credits reserved for in-progress operations. Returned as a decimal string.
    
    **Constraints**
    
    Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).