Promotional grants

A promotional grant adds credits to a subscription's credit balance. Each grant creates grant blocks to track the credit lifecycle and ledger operations to record the credit movement.

Example

A subscription receives 50 bonus AI credits as part of a promotional campaign. The grant credits the subscription's provisioned balance for the ai_credits unit, creates a grant block to track the credit lifecycle including expiry, and records the credit movement as ledger operations.

Use Cases

Reward subscribers with bonus credits

Reward subscribers with bonus credits as part of a promotional campaign.

Compensate for service disruptions or overcharges

Compensate a subscription for service disruptions or overcharges.

Sample Promotional grantJSON

API Index URL

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

Promotional grants attributes

subscription_id

required, string, max chars=50

A unique, immutable identifier for the subscription to which the promotional credits were applied.

unit_id

required, string, max chars=50

Identifier of the credit unit to which the promotional credits belong. For example, a credit unit id such as ai_credits.

amount

required, string, max chars=36

The number of credits issued as part of this promotional grant. Returned as a decimal string. Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).

expires_at

required, timestamp(UTC) in seconds

Unix timestamp (in seconds) at which the promotional credits expire and become unavailable for consumption.

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

metadata

optional, string, max chars=65k

Optional opaque JSON object carrying additional business context for this promotional grant.

Behavior

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