Prepaid Credits
Overview
Prepaid credits is a monetization model in which customers pay in advance for a balance of credits and then spend those credits as they use your product's features. Instead of pricing each feature in money, you price every feature in a credit unit you define, such as AI Credits or Tokens. Chargebee tracks a credit balance and credit ledger for each subscription and credit unit, deducts credits as the customer uses your features, and, if required, bills overage when the balance runs out.
The Prepaid Credits feature is available through early access. To enable it on your site, contact eap@chargebee.com to join the Early Adopter Program. To set up prepaid credits after it's enabled, see Configure prepaid credits.
When to use prepaid credits
Prepaid credits suit products where customers consume several usage-based features that cost different amounts. Use prepaid credits when:
- You offer several usage-based features with different costs, for example, image generation and text generation that run on different AI models.
- You want customers to commit to a spend in advance and draw it down over time.
- You want customers to decide how to spend one balance across features, instead of buying a fixed allowance for each feature.
Prepaid credits concept
| Term | Definition |
|---|---|
| Credit unit | The currency you define for credits, for example, AI Credits. A site supports up to five credit units. |
| Credit grant | The number of credits of a credit unit that a customer receives with a plan, addon, or charge, how often the credits are issued, and whether unused credits roll over. |
| Credit balance | The number of credits available to spend for a subscription and credit unit. The balance increases when credits are granted and decreases when credits are deducted or expire. |
| Credit ledger | The record of every change to the credit balance for a subscription and credit unit, including grants, deductions, expiries, and rollovers. |
| Credit overdraft limit | The maximum amount a customer's credit balance can go below zero when the credit unit has no overage pricing. |
| Credit rate | The number of credits Chargebee deducts for a quantity of usage on a metered feature, for example, 2 AI Credits per image. You set credit rates only when you deduct credits through the Usage ingestion pipeline. |
| Credit rate type | How Chargebee applies a credit rate: Per unit deducts a set number of credits for each unit of usage, and Package deducts a set number of credits for each block of units. |
| Credit rate override | A credit rate set on one subscription that replaces the metered feature's credit rate for that subscription. |
| Included usage | A free allowance of a metered feature for each billing period. Usage within the allowance doesn't deduct credits. |
| Credit drawdown | Deducting credits from the credit balance as a customer uses a metered feature. |
| Overage | Usage after the credit balance runs out, billed through a metered addon configured to bill overage for a credit grant. |
Included usage vs. credit drawdown on a metered feature
On a subscription, each metered feature uses either included usage or credit drawdown, never both. Chargebee Billing decides which one applies from the feature's included usage on that subscription:
| Included usage on the subscription | Mode | What happens to usage |
|---|---|---|
| Greater than 0 | Included usage | Usage counts against the allowance. Chargebee doesn't deduct credits. Usage beyond the allowance is billed only through a configured metered overage addon's pricing. |
| 0 or not set | Credit drawdown | Chargebee applies the feature's credit rate to the usage and deducts the resulting credits from the credit balance. |
Because a feature in credit drawdown is paid for with credits, you can't link a metered addon that bills feature overage to it. Overage for credit drawdown features is billed only as credit overage, so customers are never charged twice for the same usage.
How prepaid credits work
Prepaid credits follow the same flow from setup to billing:
- Credit unit: You define a credit unit, such as AI Credits.
- Credit grant: You add a credit grant to a plan. For an active subscription, Chargebee issues credits at the grant frequency. For a subscription that starts with a trial, plan and addon credits are issued only when the trial ends and the subscription becomes active.
- Credit rate: If you use the Usage ingestion pipeline, you set a credit rate on each metered feature that should deduct credits.
- Usage: The customer uses your product. You either send Chargebee the number of credits to deduct (Direct credit ledger) or send raw usage events (Usage ingestion pipeline).
- Deduction: Chargebee deducts credits from the credit balance, starting with the grant that expires soonest, and records each deduction in the credit ledger.
- Overage: When the credit balance runs out, Chargebee bills further usage through the credit unit's overage addon. If there's no overage addon, the balance can go below zero up to the Credit overdraft limit.
Ways to deduct credits from the prepaid credit balance
Chargebee Billing supports the following two approaches for deducting credits. The approach you choose decides whether you need metered features and credit rates.
- Direct credit ledger
- Usage ingestion pipeline
The following table captures the critical aspects of these two approaches and their key differences:
| Aspect | Direct credit ledger | Usage ingestion pipeline |
|---|---|---|
| Best for | • Credit costs that depend on several attributes at once, such as model and resolution, or pricing logic you want to keep in your application. • When you want to handle usage events on your end and only use Prepaid credit for billing. | Credit costs that follow a per-unit or package rate, especially when you already send usage events to Chargebee. |
| Who calculates the credits to deduct | You, in your application | Chargebee, using the credit rates you set. |
| What you send to Chargebee | The number of credits to deduct. | Raw usage events for metered features. |
| Metered features and credit rates required | No | Yes |
| Supported credit pricing | Any logic you build | Per unit and Package credit rates on metered features with SUM or COUNT aggregation. |
For setup steps for each approach, see Choose how to deduct credits from the prepaid credit balance.
Example: prepaid credits for an AI content platform
Acme Business is a generative AI platform where customers create images and text. Acme Business sells a Pro plan that grants each subscription a monthly balance of AI Credits that customers spend on both features. Both metered features use Per unit credit rates in this example.
| Setting | Value |
|---|---|
| Credit unit | AI Credits |
| Credit grant on the Pro Monthly plan | 10,000 AI Credits each month, no rollover |
| Credit rate for Image generation (COUNT of images) | Per unit: 2 AI Credits per image |
| Credit rate for Text generation (COUNT of text requests) | Per unit: 5 AI Credits per text request |
| Overage addon | $0.02 per AI Credit |
On one day, a Pro customer generates 50 images and makes 12 text-generation requests. That usage costs 160 AI Credits: 50 images × 2 credits = 100 credits, plus 12 text requests × 5 credits = 60 credits.
- With the Direct credit ledger, Acme Business calculates the 160 credits in its own application and sends a deduction of 160 AI Credits to Chargebee Billing.
- With the Usage ingestion pipeline, Acme Business sends one usage event for each image and one for each text request, for 50 image events and 12 text-request events on the same subscription. Chargebee Billing applies the per-unit credit rates and deducts 160 AI Credits.
In both cases, the subscription's credit balance drops from 10,000 to 9,840 AI Credits. If the customer uses 10,300 AI Credits by the end of the month, Chargebee bills the 300-credit overage at $0.02 per credit, totaling $6.00, through the overage addon.
Limitations of prepaid credits
These limitations apply to prepaid credits on every Billing site:
- You can't change the credit unit assigned to a plan or an active subscription.
- Edits to a credit grant on an active subscription take effect at the start of the next billing term. Mid-cycle proration isn't supported.
- Archiving a credit unit blocks new grants but doesn't affect existing subscriptions.
These limitations apply when you deduct credits through the Usage ingestion pipeline:
- Credit rates are supported only on metered features with SUM or COUNT aggregation. You can't set a credit rate or use credit drawdown on features with AVG, MIN, MAX, or COUNT DISTINCT aggregation, or on a feature with included usage greater than 0 on the subscription.
- Only the Per unit and Package credit rate types are supported. Tiered, volume, and multi-attribute (matrix) credit pricing isn't supported. For credit costs that depend on several attributes, use the Direct credit ledger, or create a separate metered feature for each combination.
- Usage events are processed asynchronously, so Chargebee Billing can't stop usage when the credit balance runs out. To limit usage, gate access in your application.
- Credits are deducted only for usage events within the current billing term and the grant-expiry grace period.
- Negative usage events don't return credits to the credit balance.
- You set credit rate overrides one subscription at a time.
FAQs
Can a customer's credit balance go below zero?
Yes, up to the credit unit's Credit overdraft limit. When you use the Usage ingestion pipeline, set the Credit overdraft limit to infinite so that credit deductions don't fail.
Why didn't a usage event deduct credits?
Credit rates can be set only for metered features with SUM or COUNT aggregation and zero or unset included usage. Chargebee accepts a usage event but doesn't deduct credits when any of these is true:
- The event's timestamp is outside the current billing term and the grant-expiry grace period.
- The deduction would exceed the credit unit's Credit overdraft limit.
- The metered feature uses an aggregation other than SUM or COUNT.
- The feature has included usage greater than 0 on the subscription.
- The feature has no credit rate in the subscription's credit unit.
- The subscription's credit rate override for the feature is set to 0.
Do negative usage events add credits back?
No. A usage event with a negative quantity corrects the usage summary but doesn't return credits to the credit balance.
Does changing a credit rate affect existing subscriptions?
It depends on the option you choose when you update the credit rate. Subscriptions with a credit rate override are never affected. For details, see Update a credit rate on a metered feature.
Can Chargebee block a customer from using a feature when credits run out?
No. Chargebee doesn't reject usage when the credit balance runs out. To enforce a limit, check the balance or listen for balance notifications in your application and block access there. There are no prebuilt webhook events. Configure Alerts to send webhook notifications for low-balance and overdraft-breach notifications.
See also