The allocate operation allocates credit grants to a subscription's provisioned balance.
Behavior
- Allocates the specified
amountto the subscription's provisioned balance for the givenunit_id. - Creates one grant block to track the credit-grant lifecycle, including balance, holds, expiry, and rollover.
- Creates a ledger operation of type
allocationto 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
Input Parameters
A unique, immutable identifier for the subscription to which the allocated credit grants are applied.
Optional client-supplied identifier for this allocate operation.
Behavior
- When provided, must uniquely identify this operation across the entire ledger.
- Should not conflict with any other operation, regardless of type.
- Reusing the same value is treated as a replay of the original allocation rather than a conflict, so a retry does not create a second grant block.
Constraints
- Maximum length: 50 characters.
Default value
- When omitted, Chargebee generates an identifier for the operation.
Usage
- Supply a value that you can reproduce, such as your own allocation reference, and send that same value when retrying after an unexpected response.
The number of credit grants to allocate as part of this operation. Pass this value as a decimal string.
Constraints
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.
Optional Unix timestamp (in seconds) at which the allocated credit grants become usable. Sets effective_from on the grant block created by this allocation.
Behavior
- When set to a future timestamp, the grant block is created with
statusscheduledand its credit grants stay out of the usable balance until that time. - At
effective_from, the grant block becomesavailableand its credit grants are included in the usable balance.
Default value
- When omitted, the credit grants become usable at the time of the request.
Note
effective_from is inclusive. A capture operation with a timestamp exactly equal to effective_from is eligible to consume credit grants from this grant block.
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_atmust be a future timestamp.
Returns
Summarized real-time ledger_account_balance for the
requested subscription and unit after this allocation, bundling the
provisioned_balance and
overdraft_balance for the requested unit.
The resulting ledger_operations resource for this allocate operation. Has type allocation and reflects the movement of credit grants into the subscription's provisioned balance.
The grant_blocks created for this allocation, each tracking the issued credit grants, remaining balance, holds, expiry, and rollover state for the subscription.
The ledger_entries recorded by this operation — immutable, per-grant-block movements of type credit that make up this allocation.