# Ledger operations

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


A ledger operation represents a single action recorded in the ledger that results in a state change. Each ledger operation corresponds to one atomic event, whether initiated externally or internally.

**Behavior**

-   Ledger Operations are immutable once recorded.
-   They provide traceability, idempotency, and a complete audit trail of all state transitions.

**Usage**

Serves as the fundamental unit for representing, tracking, and reconciling all changes within the system.

## Sample Ledger operation

```json
{
  "id": "9lfj6x1f5",
  "subscription_id": "1mGETgZVF2umUZq",
  "unit_id": "ai_credits",
  "unit_type": "credit_unit",
  "type": "capture_authorization",
  "amount": "10",
  "provisioned_start_balance": "100.25",
  "provisioned_end_balance": "90.25",
  "overdraft_start_balance": "20",
  "overdraft_end_balance": "20",
  "ledger_operation_timestamp": 1774978580,
  "created_at": 1774978590,
  "modified_at": 1774978591,
  "object": "ledger_operation",
  "parent_ledger_operation_id": "eyexnp6sc"
}
```

## Ledger operations attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique identifier for this ledger operation.
  
  **Behavior**
  
  -   In case of external ledger operations, the id can be optionally provided by the upstream system.
  -   In case of internal ledger operations, the id is generated by the ledger.
  -   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 operation was recorded. Always returned.

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

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

- `type` (required, enumerated string)
  Specifies the type of ledger operation, indicating the kind of business event this record represents.
  
  **Types**
  
  **External Ledger Operations**: Triggered via API calls
  
  -   `allocation` (via the allocate API)
  -   `authorize`
  -   `capture`
  -   `capture_authorization`
  -   `release_authorization`
  
  **Internal Ledger Operations**: Triggered via system processes
  
  -   `allocation` (plan-driven / configured credit grants)
  -   `expiry`
  -   `rollover`
  -   `void`
  -   `adjustment`
  -   `overdraft_settlement`
  Possible enum values:
    - `allocation`
      Credit grants allocated into an account, such as allocations created from configured credit grants or the allocate operation.
    - `capture`
      Immediate one-step debit of credit grants from the usable balance.
    - `authorize`
      Reserves credit grants (moves from `usable_balance` to `hold_amount`) for later capture or release.
    - `release_authorization`
      Returns a hold to the usable balance, or finalizes an auto-release of the hold.
    - `capture_authorization`
      Finalizes a hold, converting all or part of the held amount into a final debit; any remainder can be auto-released.
    - `expiry`
      Credit grants expired from a grant block (and related account movements).
    - `void`
      Credit grants removed from a grant block through administrative updates.
    - `rollover`
      Carry-forward of balance into a new grant block or related rollover run.
    - `adjustment`
      When overdraft is in adjustment mode, new credit grants can adjust an existing overdraft balance.
    - `overdraft_settlement`
      Finalizes overdraft usage once it has been invoiced, marking the used credits as billed.

- `amount` (required, string, max chars=36)
  Represents the quantity of credit grants affected by this ledger operation. 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 by Ledger Operation Type**
  
  -   `capture`: Credit grants debited from the account immediately.
  -   `authorize`: Credit grants reserved, moving from usable balance to hold amount.
  -   `capture_authorization`: Credit grants finalized as consumption (converted from hold amount to debited); any remaining hold amount is automatically released.
  -   `release_authorization`: Credit grants released from hold amount back to the usable balance.
  -   `expiry`: Credit grants that have lapsed after the validity and grace period.
  -   `rollover`: Credit grants carried forward into a new grant block.
  -   `void`: Credit grants removed through administrative updates.

- `provisioned_start_balance` (required, string, max chars=36)
  The provisioned account balance immediately before this ledger operation 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).
  
  **Usage**
  
  Use alongside `provisioned_end_balance` to trace exactly how each ledger operation moved the provisioned account balance over time.

- `provisioned_end_balance` (required, string, max chars=36)
  The provisioned account balance immediately after this ledger operation 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).
  
  **Usage**
  
  Use alongside `provisioned_start_balance` to trace exactly how each ledger operation moved the provisioned account balance over time.

- `overdraft_start_balance` (required, string, max chars=36)
  The overdraft account balance immediately before this ledger operation 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).
  
  **Usage**
  
  Use alongside `overdraft_end_balance` to trace exactly how each ledger operation moved the overdraft account balance over time.

- `overdraft_end_balance` (required, string, max chars=36)
  The overdraft account balance immediately after this ledger operation 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).
  
  **Usage**
  
  Use alongside `overdraft_start_balance` to trace exactly how each ledger operation moved the overdraft account balance over time.

- `parent_ledger_operation_id` (optional, string, max chars=50)
  The `ledger_operation_id` of the parent `authorize` ledger operation associated with this ledger operation.
  
  **Usage**
  
  -   Present on `capture_authorization` and `release_authorization` ledger operations to identify the hold being finalized or released.
  -   Also present on internally generated release ledger operations (for example, partial-capture remainders) to correlate them back to the original authorization.
  
  **Constraints**
  
  -   Must match the `ledger_operation_id` used in the original `authorize` call.
  -   The same value should be reused across retries.

- `ledger_operation_timestamp` (required, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) representing when the business event occurred in the upstream system. Used for period attribution, grace-period eligibility, and reporting accuracy.
  
  **Note**
  
  Late or out-of-order submissions appear in arrival order, while attribution and eligibility logic rely on `ledger_operation_timestamp`.
  
  **Constraints**
  
  -   The `ledger_operation_timestamp` must be within the last 10 minutes from the time of the request.
  -   Grant blocks outside their active window (including those in the grace period) are not eligible for authorization and are excluded from balance checks for this ledger operation.

- `auto_release_timestamp` (optional, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) indicating when an unfinalized hold amount from an authorize request will be automatically released back to the usable balance.
  
  **Behavior**
  
  -   Applies only to authorize ledger operations.
  -   If not explicitly provided, the system assigns a default expiry.
  -   Defaults to approximately 10 minutes after the authorize request is processed.
  
  **Usage**
  
  Ensures held credit grants are not locked indefinitely by abandoned or unfinalized authorizations.
  
  **Note**
  
  -   By default, the value reflects what is provided in the request.
  -   If the specified timestamp exceeds the end of the block's grace period, it is adjusted (clamped) to the grace period end and returned in the response.

- `created_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) indicating when this ledger operation was recorded in the system.
  
  **Behavior**
  
  -   Automatically set by the system at the time of persistence.
  -   Immutable and cannot be modified once written.
  
  **Note**
  
  Serves as the source of truth for ordering ledger operations and tracking how they affected the balance over time.

- `modified_at` (required, timestamp(UTC) in seconds)
  Unix timestamp (in seconds) indicating when this ledger operation record was last updated in the system.
  
  **Behavior**
  
  Automatically updated by the system whenever the record is modified.

- `metadata` (optional, jsonobject)
  Optional opaque JSON object carrying additional business context
  
  **Behavior**
  
  -   Stored as-is and returned verbatim by the system.
  -   Not interpreted, validated, or indexed by the system.