Introducing OpenTelemetry for Chargebee SDKs — trace every API call in any telemetry tool.
Chargebeechargebee API

Ledger entries

A ledger entry is the lowest-level, immutable record of a single movement of credit grants against one grant block. While a ledger operation 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 field conveys the direction of each movement; amount is always positive.

Usage

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

Sample Ledger entryJSON

API Index URL

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

Ledger entries attributes

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
optional, string, max chars=50

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

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

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.

unit_id
optional, string, max chars=50

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

unit_type
optional, enumerated string

Type of unit used for this entry.

Enum Values
credit_unit

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

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. 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.
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. 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. 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) immediately before this ledger entry 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).

account_end_balance
required, string, max chars=36

The account balance (provisioned or overdraft, matching account_type) immediately after this ledger entry 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).

type
required, enumerated string

Specifies the direction of the movement of credit grants recorded by this entry.

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