Ledger operations

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 operationJSON

API Index URL

https://[site].chargebee.com/api/v2/ledger_operations

Ledger operations attributes

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.

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

authorize
capture
capture_authorization
release_authorization

Internal Ledger Operations: Triggered via system processes

allocation
expiry
rollover
void
adjustment

Enum Values

allocation

Credits issued into an account, such as allocations created from configured credit grants or promotional grants.

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

Credits 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.

amount

required, string, max chars=36

Represents the quantity of credit grants affected by this ledger operation. Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).

Behavior by Ledger Operation Type

capture: Credits debited from the account immediately.
authorize: Credits reserved, moving from usable balance to held amount.
capture_authorization: Credits finalized as consumption (converted from held to debited); any remaining held credits are automatically released.
release_authorization: Credits released from hold back to the usable balance.
expiry: Credits that have lapsed after the validity and grace period.
rollover: Credits carried forward into a new grant block.
void: Credits removed through administrative updates.

start_balance

required, string, max chars=36

The usable credit balance immediately before this ledger operation was applied. Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).

Usage

Use alongside end_balance to trace exactly how each ledger operation moved the balance over time.

end_balance

required, string, max chars=36

The usable credit balance immediately after this ledger operation was applied. Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).

Usage

Use alongside start_balance to trace exactly how each ledger operation moved the balance over time.

provisioned_start_balance

required, string, max chars=36

The provisioned account balance immediately before this ledger operation was applied. Returned as a decimal string. 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. 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. 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. 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

optional, 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 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 credits 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.

metadata

optional, string, max chars=65k

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.

created_at

optional, 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

optional, 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.

subscription_id

optional, string, max chars=50

A unique, immutable identifier for the subscription against which this ledger operation was recorded.

unit_id

optional, string, max chars=100

Identifier of the credit unit this ledger operation affects. For example, a credit unit id such as ai_credits.

unit_type

optional, enumerated string

Type of unit used for this ledger operation.

Enum Values

credit_unit

The unit represents a credit unit, the type used by credit grants.