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

Allocate

The allocate operation allocates credit grants to a subscription's provisioned balance.

Behavior

  • Allocates the specified amount to the subscription's provisioned balance for the given unit_id.
  • Creates one grant block to track the credit-grant lifecycle, including balance, holds, expiry, and rollover.
  • Creates a ledger operation of type allocation to record the movement of credit grants.

Usage

Use this operation to allocate ad-hoc credit grants to a subscription — for example, to reward subscribers with bonus credit grants or compensate for service disruptions.

The response returns the created ledger_operations, the updated ledger_account_balance, the created grant_blocks, and the ledger_entries recorded by this operation.

Sample Request

Sample Result[JSON]

URL Format

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

Input Parameters

subscription_id
required, string, max chars=50

A unique, immutable identifier for the subscription to which the allocated credit grants are applied.

unit_id
required, string, max chars=50

Identifier of the credit unit for which credit grants are allocated. For example, a credit unit id such as ai_credits.

amount
required, string, max chars=36

The number of credit grants to allocate as part of this operation. Pass this value as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).

Behavior

  • Must be a positive value greater than zero.
  • Allocated to the subscription's provisioned balance for the given unit_id.

Example

If amount = "500", then 500 credit grants are added to the subscription's total as well as usable balance and recorded as a new grant block.

expires_at
required, timestamp(UTC) in seconds

Unix timestamp (in seconds) at which the allocated credit grants expire and become unavailable for consumption.

Behavior

  • Once expired, the remaining balance in the associated grant block moves to expired_amount.

Constraints

  • expires_at must be a future timestamp.
metadata
optional, jsonobject

Optional opaque JSON object carrying additional business context for this allocation.

Behavior

  • Stored as-is and returned verbatim by the system.
  • Not interpreted, validated, or indexed by the system.

Returns

ledger_account_balance
Ledger account balance object
Resource object representing ledger_account_balance
ledger_operations
always returned
Resource object representing ledger_operation
grant_blocks
always returned
Resource object representing grant_block
ledger_entries
always returned
Resource object representing ledger_entrie