Configure Prepaid Credits

Overview

This page explains how to set up prepaid credits in Chargebee Billing: choose how to deduct credits, define a credit unit, grant credits on a plan, set credit rates, configure overage, create subscriptions, and deduct credits.

For concepts, a worked example, and limitations, see Prepaid credits.

Choose how to deduct credits from the prepaid credit balance

Decide how you'll deduct credits before you start, because the approach decides which steps you complete.

• Direct credit ledger: Your application calculates how many credits each action costs and sends that number to Chargebee. Choose this approach when credit costs depend on several attributes at once, such as model and resolution, or when you want to keep pricing logic in your application.
• Usage ingestion pipeline (Recommended): You send raw usage events for metered features, and Chargebee applies credit rates to calculate and deduct credits. Choose this approach when credit costs follow a per-unit or package rate, especially if you already send usage events to Chargebee Billing. With this approach, you do not have to manage the conversion of usage to credits on their end.

Prerequisites

Before you configure prepaid credits, make sure that:

• Prepaid credits is available through early access. Contact eap@chargebee.com to join the Early Adopter Program.
• If you plan to use the Usage ingestion pipeline, your metered features use SUM or COUNT aggregation and you send usage events to Chargebee. See Defining Metered Features and Ingesting Usage Events into Chargebee.

Step 1: Define a credit unit for prepaid credits

A credit unit is the currency customers spend when they use your product's features, for example, AI Credits.

Create a credit unit

To create a credit unit, follow these steps:

1. Click Settings > Configure Chargebee > Credit Units.

   

2. Click Create a credit unit.

3. Enter the credit unit details.

   

4. Click Create.

The following fields are available when you create a credit unit:

You can define up to five credit units per site.

Set the allowed negative balance for the Usage ingestion pipeline

If you deduct credits through the Usage ingestion pipeline, set the allowed negative balance to infinite. Usage events are processed asynchronously, so Chargebee can't guarantee a strict cutoff when a balance reaches the limit. If a credit deduction would go past the allowed negative balance, Chargebee still accepts the usage event, but the credit deduction fails and the usage isn't deducted from the credit balance.

Leaving the Allowed negative balance field blank sets the limit to zero, not to infinite. To set an infinite allowed negative balance, create the credit unit with the Create a credit unit API and set is_unlimited to true. Omit overdraft_amount.

Edit a credit unit

You can update the External name and Internal name of a credit unit at any time.

Renaming a credit unit doesn't affect existing subscriptions. Customers on active subscriptions continue to see the previous name, and the new name applies only to new plans and future configurations. For example, if you rename AI Credits to Tokens, existing customers still see AI Credits, and only newly created plans show Tokens.

Archive a credit unit

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

Step 2: Configure a credit grant for prepaid credits

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 a credit grant to a plan, follow these steps:

1. Click Product Catalog > Plans and select the plan.

2. Go to the plan's item price.

3. In the Credit Grant section, click Configure Grant.

   

4. Enter the grant settings.

   

5. Click Save.

The following settings are available for a credit grant:

Credit grant rollover options

View and edit credit grant versions

Each change to a credit grant creates a new version. Each version records the grant quantity, frequency, and rollover settings at the time it was created. Edits don't affect existing subscriptions.

To view the version history, go to the plan's item price and select Credit Grant > Versions.

To edit a credit grant, follow these steps:

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

Step 3: Set credit rates on metered features

This step applies only when you deduct credits through the Usage ingestion pipeline. If you use the Direct credit ledger, go to Step 4.

A credit rate tells Chargebee how many credits to deduct for usage on a metered feature. Before you set a credit rate, make sure that:

• The metered feature uses SUM or COUNT aggregation. Credit rates aren't supported for AVG, MIN, MAX, or COUNT DISTINCT aggregation.
• The credit unit you want to deduct from exists.
• The feature has no included usage on subscriptions that should use credit drawdown. A feature with included usage greater than 0 on a subscription doesn't deduct credits on that subscription.

Set a credit rate on a metered feature

To set a credit rate, follow these steps:

1. Click Usages > Metered Features and select the metered feature.

2. In the Credit rate section, click Set credit rate.

   

3. Select the Credit unit.

4. Select the Credit rate type: Per unit or Package.

   

5. Enter the number of credits. For Package, also enter the package size.

6. Click Save.

Credit rate types: Per unit and Package

Update a credit rate on a metered feature

Each change to a credit rate on a metered feature creates a new version. New subscriptions always use the latest version. Each existing subscription keeps the version that was in effect when it was created until it moves to a newer one.

When you update a credit rate, choose how existing subscriptions adopt the change:

A credit rate update never changes a subscription that has a credit rate override for that feature. The same choice applies when you set a credit rate for the first time on a metered feature that existing subscriptions already use. If you choose Apply at renewal in that case, those subscriptions start deducting credits for usage that previously didn't deduct credits, so inform affected customers before you save.

Step 4: Configure overage pricing for a credit unit

When customers use more credits than their credit grant, you can charge them an overage rate through a metered addon.

Create a metered addon for credit overage

To create an overage addon, follow these steps:

1. Click Product Catalog > Addons > Create a new addon.

2. Enter 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, for example, AI Credits.

   

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

Credit overage billing rules

• Customers are charged the overage rate only after they use up their credit grant.
• A metered addon bills overage for either an entitlement feature or a credit unit grant, not both.
• A metered addon supports one overage model at a time.
• A metered addon can't include a credit grant. To give an addon a credit grant, configure it as a non-metered addon.
• You can't link a metered addon that bills feature overage to a metered feature that uses credit drawdown. Chargebee blocks this configuration so customers aren't charged twice for the same usage.

Step 5: Create a subscription with prepaid credits

When a customer subscribes to a plan with a credit grant, Chargebee Billing provisions the credits to the subscription automatically.

Create a subscription with a credit grant

To create a subscription, follow these steps:

1. Go to the customer's record and click Create a subscription.

2. Select the product family and plan. The subscription shows the credit grant details, such as the credit quantity and frequency (for example, 16,500 AI Credits/month).

   

3. Optionally, add recurring addons, one-time charges, or an overage addon.

4. Click Create.

Start a trial with prepaid credits

You can start a subscription that uses prepaid credits with a trial period that begins immediately. Chargebee grants plan and addon credits only when the trial ends and the subscription becomes active, so the trial doesn't use the customer's first paid credit grant. No extra setup is required.

Override the credit grant on a subscription

You can customize the credit grant for one subscription without changing the plan's credit grant. Overrides apply only to the selected subscription, and you can't change the credit unit.

To override a credit grant, follow these steps:

1. During subscription creation, click the three-dot menu next to the plan.

2. Select Manage Credit Grants.

   

3. Change the grant frequency, grant quantity, and rollover as needed.

   

4. Click Save.

Edit a credit grant on an active subscription

You can update a credit grant on an active subscription at any time. Changes take effect from the next billing term. Mid-cycle proration isn't supported.

Set a credit rate override on a subscription

This section applies only when you deduct credits through the Usage ingestion pipeline. Use a credit rate override when one customer needs a different credit rate than the metered feature's credit rate, for example, a negotiated discount. A credit rate override always takes precedence over the metered feature's credit rate, including any later updates to it.

Once the subscription is created, you will be able to see the credit rate for all the features that apply to the subscription based on the credit grant in the subscription details.

To set a credit rate override, follow these steps:

1. Navigate to the Credit rate section in the subscription record and click Manage.

2. Click Override and make necessary changes.

   

3. Click Apply > Save Changes.

A credit rate override must use a credit unit that the subscription has a credit grant for.

Step 6: Deduct credits from the prepaid credit balance

Deduct credits using the approach you chose in Choose how to deduct credits from the prepaid credit balance.

Option A: Deduct credits through the Direct credit ledger

With the Direct credit ledger, your application calculates the credits each action costs and asks Chargebee to deduct them. Chargebee doesn't use metered features or credit rates for these deductions.

To deduct credits, follow these steps:

1. In your application, calculate the number of credits the customer's action costs.
2. Send a credit deduction for the subscription and credit unit through the credit ledger API. See the Ledger operations API reference for immediate deductions (capture) and the Authorize API reference for reserving credits as holds before finalizing consumption.
3. To verify the deduction, open the subscription and check its credit balance and credit ledger.

Chargebee deducts credits from the grant that expires soonest first.

Option B: Deduct credits through the Usage ingestion pipeline

With the Usage ingestion pipeline, you send usage events, and Chargebee calculates and deducts the credits. For each usage event, Chargebee:

1. Finds the credit rate for the feature: the subscription's credit rate override if one exists, otherwise the metered feature's credit rate.
2. Applies the credit rate to the usage quantity to calculate the credits.
3. Deducts the credits from the grant that was valid at the event's timestamp, starting with the grant that expires soonest.
4. Records the deduction in the subscription's credit ledger.

To deduct credits through the Usage ingestion pipeline, follow these steps:

1. Complete Steps 1 through 5, including credit rates on your metered features.
2. Send usage events for the metered features. Use the Usage events API: Ingest a Usage Event for individual events or Ingest Usage Events in Batch for bulk submissions.
3. To verify the deduction, open the subscription and check its credit balance and credit ledger.

Rules for deducting credits through the Usage ingestion pipeline

These rules decide whether a usage event deducts credits. In each case, Chargebee still accepts and records the usage event.

Allowed negative balance. If a deduction would go past the credit unit's allowed negative balance, the credit deduction fails. Set the allowed negative balance to infinite, as described in Set the allowed negative balance for the Usage ingestion pipeline.

Subscriptions with a credit grant. Credit drawdown occurs only when the subscription has an available credit grant. Otherwise, the deduction fails.

Negative usage events. A usage event with a negative quantity corrects the usage summary but doesn't return credits to the credit balance.

Billing term and grant-expiry grace period. Chargebee deducts credits only for usage events whose timestamp falls within the current billing term and the grant-expiry grace period. The grant-expiry grace period is 12 hours by default. For a late event, Chargebee deducts credits from the grant that was valid at the event's timestamp if the event arrives within that grant's expiry grace period. Events with a timestamp outside this window are ingested, but the credit deduction fails.

For example, a subscription has monthly billing terms and a 12-hour grant-expiry grace period. A usage event with a timestamp of August 31 at 11:55 PM arrives on September 1 at 6:00 AM. Because it arrives within the grace period, Chargebee deducts credits from the August grant, not the September grant.

Supported aggregations. Only metered features with SUM or COUNT aggregation deduct credits. Usage for features with AVG, MIN, MAX, or COUNT DISTINCT aggregation doesn't deduct credits.

Features without credit drawdown. Usage doesn't deduct credits when the feature has included usage greater than 0 on the subscription, has no credit rate in the subscription's credit unit, or has a Disabled credit rate override.

No usage cutoff. Chargebee doesn't reject usage events when the credit balance runs out. To block usage at a limit, gate access in your application.