# Ledger entries

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


A ledger entry is the lowest-level, immutable record of a single movement of credit grants against one [grant block](/docs/api/grant_blocks). While a [ledger operation](/docs/api/ledger_operations) represents the business action (for example, a `capture` or `authorize`), each operation is expanded internally into one or more ledger entries that describe exactly how individual grant blocks were affected.

**Behavior**

-   Ledger entries are immutable once recorded.
-   A single ledger operation can generate multiple entries. When a capture (or other consumption) spans several grant blocks, a ledger entry is created corresponding to each grant block, reflecting the amount captured from that grant block.
-   The [`type`](#type) field conveys the direction of each movement; [`amount`](#amount) is always positive.

**Usage**

Ledger entries provide the granular, per-grant-block audit trail.

## Sample Ledger entry

```json
{
  "id": "le_capture_001",
  "subscription_id": "1mGETgZVF2umUZq",
  "unit_id": "ai_credits",
  "unit_type": "credit_unit",
  "account_type": "provisioned",
  "amount": "10.35",
  "grant_block_start_balance": "100.25",
  "grant_block_end_balance": "89.9",
  "account_start_balance": "100.25",
  "account_end_balance": "89.9",
  "type": "debit",
  "ledger_operation_id": "tu80phup1",
  "grant_block_id": "gb_ai_credits_001",
  "created_at": 1774978599,
  "modified_at": 1774978599,
  "object": "ledger_entry"
}
```

## Ledger entries attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique identifier for this ledger entry.
  
  **Behavior**
  
  -   Automatically assigned by the ledger at creation time.
  -   Immutable and cannot be modified once written.

- `subscription_id` (required, string, max chars=50)
  A unique, immutable identifier for the [subscription](/docs/api/subscriptions/subscription-object#id) against which this ledger entry was recorded. Always returned.

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

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

- `account_type` (required, enumerated string)
  The account this entry belongs to: **provisioned** (credit grants issued per the plan, consumed first) or **overdraft** (consumption beyond the configured credit grants, after the provisioned account is exhausted). Always returned.
  Possible enum values:
    - `provisioned`
      Stores the credit grants given as per the plan configuration. Consumption of credit grants is first done through this account.
    - `overdraft`
      Allows consumption beyond the configured credit grants. Used once the credit grants in the provisioned account are exhausted.

- `amount` (required, string, max chars=36)
  The number of credit grants moved by this entry against a single grant block. Returned as a decimal string.
  
  **Constraints**
  
  Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).
  
  **Behavior**
  
  -   Always a positive value; the direction of the movement is conveyed by [`type`](#type).

- `grant_block_start_balance` (required, string, max chars=36)
  The grant block balance immediately before this ledger entry was applied. Returned as a decimal string.
  
  **Constraints**
  
  Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).

- `grant_block_end_balance` (required, string, max chars=36)
  The grant block balance immediately after this ledger entry was applied. Returned as a decimal string.
  
  **Constraints**
  
  Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).

- `account_start_balance` (required, string, max chars=36)
  The account balance (provisioned or overdraft, matching [`account_type`](#account_type)) immediately before this ledger entry was applied. Returned as a decimal string.
  
  **Constraints**
  
  Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).

- `account_end_balance` (required, string, max chars=36)
  The account balance (provisioned or overdraft, matching [`account_type`](#account_type)) immediately after this ledger entry was applied. Returned as a decimal string.
  
  **Constraints**
  
  Maximum supported value: `9999999999999999999999999.9999999999` (up to 25 digits before the decimal and up to 10 digits after).

- `type` (required, enumerated string)
  Specifies the direction of the movement of credit grants recorded by this entry.
  Possible enum values:
    - `credit`
      Credit grants added when a grant block is allocated.
    - `debit`
      Credit grants consumed from a grant block.
    - `hold`
      Credit grants reserved on a grant block by an authorize operation, moved from usable balance to hold amount.
    - `unhold`
      Credit grants released allowing the amount to go from hold amount back to the usable amount via release\_authorization or the auto-release job.

- `ledger_operation_id` (required, string, max chars=50)
  Identifier of the [ledger operation](/docs/api/ledger_operations) that produced this entry. Multiple entries can share the same `ledger_operation_id` when a single operation spans more than one grant block or produces more than one movement.

- `grant_block_id` (required, string, max chars=50)
  Identifier of the [grant block](/docs/api/grant_blocks) this entry acts upon.

- `created_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) indicating when this ledger entry was recorded in the ledger.
  
  **Behavior**
  
  -   Automatically set by the ledger at creation time.
  -   Immutable and cannot be modified once written.

- `modified_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) indicating when this ledger entry record was last updated in the ledger.