Prepaid credits for usage-based billing

Prepaid credits help you monetize usage-based features in your product. Instead of charging customers on a fixed subscription alone, you can issue credits that customers spend as they use your platform's features.

This guide walks you through setting up credit units, configuring credit grants on plans, adding overage pricing, and creating subscriptions.

Example use case

Let's consider Acme Business, a generative AI-driven platform for image and video creation. Users produce content across different formats and quality levels using prompts and customizable configurations.

To monetize usage-based features, Acme Business creates AI Credits, a credit unit customers spend each time they generate content. The cost in AI Credits varies by model, resolution, and input type.

The steps in this guide follow the Acme Business setup as a worked example.

Before you begin

Understand these key concepts:

• Credit unit: The named unit of value customers spend (for example, AI Credits or Tokens). You can define up to five credit units per Chargebee Billing site.
• Credit grant: The quantity of a credit unit allocated to a customer when they subscribe to a plan or addon.
• Overage: A metered addon that charges customers when they exceed their allocated credit grant.

Step 1: Define a credit unit

A credit unit is the foundation of your prepaid billing setup. It represents the unit of measurement customers spend when they use your product's features.

Create a credit unit

To configure credit units in your Billing site, follow these steps:

1. Click Settings > Configure Chargebee > Credit Units.

2. Select Create a credit unit.
3. Fill in the following fields:

4. Click Create.

Edit a credit unit

Update the External name and Internal name of a credit unit at any time.

Changes to a credit unit's name do not affect existing subscriptions. Customers on active subscriptions continue to see the previous name. The updated name applies only to new plans and future configurations.

For example, if you rename "AI Credits" to "Tokens," customers already subscribed will still see "AI Credits." Only newly created plans will display "Tokens."

Archive a credit unit

Archiving a credit unit prevents new grants from being issued or configured for that unit. Existing subscriptions that use the credit unit are not affected and continue to work normally.

Step 2: Configure a credit grant for a plan

A credit grant defines how many credits a customer receives when they subscribe to a plan, addon, or charge.

Add a credit grant to a plan

To add credit grant to an existing plan in your Billing site, follow these steps:

1. Click Product Catalog > Plan > select the plan.
2. Navigate to the plan's item price.
3. In the Credit Grant section, click Configure Grant.

3. Set the following:

4. Click Save.

Rollover options

View and edit grant version history

After a credit grant is configured, track changes over time.

1. Navigate to the plan's item price.
2. Go to Credit Grant > Versions.

Each version records the grant quantity, frequency, and rollover configuration at the time it was created.

To update a credit grant:

1. Select the three-dot menu next to the grant.
2. Select Edit.
3. Make your changes and select Save.

Edits create a new version. Existing subscriptions are not affected.

Step 3: Configure overage pricing

When customers exceed their allocated credit grant, charge them an overage rate using a metered addon.

Create a metered addon for overage

To create a metered addon in your Billing site, follow these steps:

1. Click Product Catalog > Addons > Create a new addon.
2. Fill in the addon name and ID.

3. Select This is a metered addon billing on-demand usage.
4. Under How would you want to use this metered addon?, select Bill overage for credit grant.
5. Under Choose credit unit of the grant, select the credit unit this addon applies to (for example, AI Credits).

6. Save the addon, then open the addon's item price to set the overage price and billing frequency.

Overage billing rules

• Customers are charged the overage rate only after they exceed their allocated credit grant.
• Configure overage billing for either a specific entitlement feature or a credit unit grant, not both on the same metered addon.
• Only one overage model can be applied per metered addon at a time.

Step 4: Create a subscription with credit grants

Create a subscription

When a customer subscribes to a plan that has a credit grant configured, credits are automatically provisioned to the subscription.

1. Go to the customer's record and select Create a subscription.
2. Select the product family and plan.
3. The subscription displays the credit grant details, such as the credit quantity and frequency (for example, 16,500 AI Credits/month).

4. Optionally, add recurring addons, one-time charges, or an overage addon.
5. Select Create.

Override credit grant settings for a specific subscription

Customize the credit grant for an individual subscription without changing the plan-level configuration.

1. During subscription creation, select the three-dot menu next to the plan.
2. Select Manage Credit Grants.

3. Adjust the grant frequency, grant quantity, and rollover behavior as needed.

4. Click Save.

Overrides apply only to the selected subscription. The original plan-level grant configuration remains unchanged. The credit unit cannot be changed during an override.

Edit a credit grant on an active subscription

Update a credit grant on an active subscription at any time. Changes made mid-cycle take effect from the next billing term.

Limitations and considerations

• Define up to five credit units per Chargebee site.
• The credit unit assigned to a plan or active subscription cannot be changed.
• Edits to credit grants on active subscriptions take effect at the start of the next billing term.
• Archiving a credit unit blocks new grants but doesn't affect existing subscriptions.
• A metered addon cannot include a credit grant. Non-metered addons can.