Credit Units

Credit units power credit-based billing for usage-based products, letting you get paid upfront while customers spend credits as they use your product's features. Each credit unit is a customizable consumption unit, such as AI credits or API calls, that you define beyond Chargebee's built-in pricing dimensions.

When should you use credit units?

Credit units are a good fit when:

Customers have widely varying usage patterns
Business costs scale with consumption
Upfront cash flow is preferred

How does it work?

Create a credit unit (say, "AI Credits")
Configure credit grants on your plans (e.g., a Pro Plan priced at $20 USD includes 100 AI Credits)
Track customer usage in real time
Bill for actual consumption

What happens when credits are exhausted?

Once the provisioned credits are exhausted, further consumption draws from the overdraft balance up to its configured limit. Configure overdraft behavior for a credit unit using is_unlimited and overdraft_amount, so customers can continue consuming, purchase more, or pay for overage depending on your setup.

Sample Credit unitJSON

API Index URL

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

Credit Units attributes

required, string, max chars=50

A unique and immutable identifier for the credit unit.

name

required, string, max chars=50

Internal display name for the credit unit. This must be unique across the site.

external_name

required, string, max chars=50

Customer-facing display name for the credit unit. This must be unique across the site. If not provided during creation, name is used as the default.

status

optional, enumerated string

The current lifecycle status of the credit unit.

Enum Values

active

Grant configuration for items and grant configuration overrides at subscription layer can be created for active credit units.

archived

Grant configuration for items and grant configuration overrides at subscription layer cannot be created for archived credit units. Already configured grants for credit units continue to be effective.

resource_version

optional, long

The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.

updated_at

optional, timestamp(UTC) in seconds

The time at which the credit unit was last updated.

created_at

required, timestamp(UTC) in seconds

The time at which the credit unit was created.

created_by

optional, string, max chars=100

The source (or the user) from where the credit unit has been created.

updated_by

optional, string, max chars=100

The source (or the user) from where the credit unit has been last updated.

is_unlimited

required, boolean

Indicates whether this credit unit allows unlimited overdraft consumption. When true, grace consumption continues without a cap after the allocated grants are exhausted. When false, grace consumption is capped by overdraft_amount.

overdraft_amount

optional, string, max chars=50

The amount up to which grace consumption is allowed after the allocated grants are exhausted. A positive decimal value that applies only when is_unlimited is false.