Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.
Chargebeechargebee API

Create promotional grant

Idempotency Supported

Issues promotional credits to a subscription's credit balance.

API Behavior

  • Credits the specified amount to the subscription's provisioned balance for the given unit_id.
  • Creates one or more grant blocks to track the credit lifecycle, including balance, holds, expiry, and rollover.
  • Creates ledger operations to record the credit movement.

Use Cases

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

Compensate a subscription for service disruptions or overcharges.


The response returns the created ledger_operations and grant_blocks arrays.

Sample Request

Sample Result[JSON]

URL Format

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

Input Parameters

subscription_id
required, string, max chars=50

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

unit_id
required, string, max chars=50

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

amount
required, string, max chars=36

The number of credits to issue as part of this promotional grant. 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.
  • Credited to the subscription's provisioned balance for the specified unit.
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.

Constraints

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

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.

Returns

ledger_operations
always returned
Resource object representing ledger_operation
grant_blocks
always returned
Resource object representing grant_block