Sell annual plans that grant included credits every month used across products and charge overage monthly

Overview

If your business sells prepaid credits where every product draws from a common pool, and you invoice customers for usage past the grant, this guide shows you how to build that model in Chargebee Billing. You define one credit unit and a credit rate on each metered feature. You send usage events. Chargebee converts that usage into credits and deducts them from the shared balance. A metered addon invoices for credits consumed past the grant.

Throughout this guide, you configure the model for a single running example. Acme Inc. sells three products: Article generation, Image generation, and Video generation that draw down from a common credit balance called AI Credits. Each plan decides how large that balance is.

John Doe subscribes to Growth: $12,000 per year, with 10,000 AI Credits granted each month. Chargebee deducts 1 AI Credit per article, 10 per image, and 50 per video from the usage events you send. Unused credits expire at the end of the grant period. If John uses 12,400 AI Credits in a month, the 2,400 credits past the grant are invoiced that month at $0.10 each ($240). Enterprise is $30,000 per year, with 50,000 AI Credits granted each month, and uses the same overage rate.

How this billing model works

The illustration below explains how this billing model works:

Before you start

If you don't already have a Chargebee Billing account, click here to sign up.

Advanced Usage-Based Billing is enabled by default for new Chargebee Billing sites. If you are an existing user, enable it before you build the model.

Multi-Frequency Billing is enabled by default for new Chargebee Billing sites. If you are an existing user, enable it before you build the model.

Prepaid Credits is in early access. Contact Chargebee Support to request access before you build the model.

Validate before go-live

When you enter Time Machine, existing subscriptions and customer details on the test site are erased and cannot be recovered. Export the data first if you need a backup.

Before enabling this on a live site, validate one grant cycle on a test site with Time Machine. Create a Growth subscription with the overage addon attached. Confirm the monthly grant of 10,000 AI Credits. Ingest article, image, and video events that stay inside the grant, then ingest events that take the month past 10,000. Advance to the next month and confirm an overage invoice for the excess at $0.10 per AI Credit, and a fresh grant of 10,000 AI Credits. A test site offers a one-year Time Machine option when you also want to validate annual renewal.

When you are ready to go live, copy the configuration and Product Catalog from the test site to the live site with Transfer Configurations. To transfer customer, subscription, or invoices data, you can import them on your live site.

Implementation steps

Follow these steps in order. Each step shows how to do the task in the Chargebee Billing app and with the API.

1. Define the credit unit

A credit unit is the named unit or currency your customers spend. Create it once. Grants, credit rates, usage-event deductions, and credit-balance alerts all use this unit. Article generation, image generation, and video generation share it.

curl  https://{site}.chargebee.com/api/v2/credit_units \
     -u {site_api_key}:\
     -d id="ai_credits" \
     -d name="AI Credits" \
     -d external_name="AI Credits" \
     -d is_unlimited=true

2. Define how usage converts to credits

Your application sends raw usage, such as the number of images generated. Chargebee converts that usage into AI Credits with the credit rate you set on each metered feature. Define these credit rates right after the credit unit, so the grants, the overage addon, and the usage deductions in the later steps all use the same conversion.

Create one metered feature per product, with SUM aggregation, and set a per-unit credit rate in AI Credits. Do not set included usage on these features. Included usage greater than 0 stops credit drawdown for that feature on that subscription. Do not link a metered addon that bills feature overage to these features. Overage is billed only through the AI Credits overage addon you create in step 4.

Credit rates are supported on SUM and COUNT aggregation only. Per unit and package are the supported credit rate types. A new credit rate version applies to new subscriptions immediately. Choose Apply to new subscriptions to leave existing subscriptions on the current rate, or Apply at renewal to move them at the next renewal. A subscription with a credit rate override is not affected.

3. Define the credit grants for your plans

The plan is the yearly fee. The credit grant on the plan price is the monthly allowance and the rollover policy. Growth and Enterprise grant different quantities of the same credit unit.

3a. Create the plans

Create Growth and Enterprise. You link pricing and the credit grant in the next steps.

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="growth" \
     -d name="Growth" \
     -d type="PLAN" \
     -d item_family_id="{item_family_id}"

3b. Define the plan price points

Once each plan is saved, create a yearly price point for it. Growth is $12,000. Enterprise is $30,000.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="growth-USD-yearly" \
     -d item_id="growth" \
     -d name="Growth USD yearly" \
     -d pricing_model="FLAT_FEE" \
     -d price=1200000 \
     -d currency_code="USD" \
     -d period_unit="YEAR" \
     -d period=1

3c. Configure the monthly credit grant and rollover

Grant frequency can be shorter than the billing frequency. These plans bill yearly and issue credits monthly. Both grants use AI Credits. Only the quantity differs.

Edits to a saved grant create a new version. Existing subscriptions keep the grant version they already have. See Prepaid credits.

4. Define how to bill overages past the credit grant

Metered addons are catalog items that let you measure and rate metered features beyond the included usage granted through the plan. In this case, the addon bills AI Credits consumed after the monthly grant is exhausted. Customers are charged the overage rate only after they exceed their allocated credit grant.

4a. Create the overage addon

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="on-demand-ai-credits" \
     -d name="On-demand AI Credits" \
     -d type="ADDON" \
     -d item_family_id="{item_family_id}" \
     -d metered=true

4b. Define the addon price point

Once the addon is created, create a monthly price point for it. Growth and Enterprise share this price. The plan only changes how many credits were granted.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="on-demand-ai-credits-USD-monthly" \
     -d item_id="on-demand-ai-credits" \
     -d name="On-demand AI Credits USD monthly" \
     -d pricing_model="PER_UNIT" \
     -d price=10 \
     -d currency_code="USD" \
     -d period_unit="MONTH" \
     -d period=1

5. Deduct credits through the usage ingestion pipeline

Chargebee converts usage events into credits with the credit rates you set in step 2 and deducts them from the shared balance. Your application sends the raw usage. It does not calculate the credit amount.

Send one usage event per article, image, or video. Usage events use the ingest host. See Ingest a usage event.

curl  https://{site}.ingest.chargebee.com/api/v2/usage_events \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "deduplication_id": "image-0001",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "image_count": 1
     }
}'

Chargebee applies the credit rate, deducts the credits from the grant that expires soonest, and records the deduction. Credits inside the monthly grant are covered by the plan fee. With is_unlimited set to true on the credit unit, deductions can continue after that grant is exhausted. Those additional credits are invoiced on the On-demand AI Credits addon at $0.10 each. On Growth, a month that consumes 12,400 AI Credits invoices 2,400 credits ($240). On Enterprise, overages start after 50,000 AI Credits.

If a deduction would pass the allowed negative balance, Chargebee still accepts the usage event, but the credit deduction fails. A negative usage quantity corrects the usage summary and does not return credits. Events outside the current billing term and the 12-hour grant-expiry grace period are ingested and do not deduct credits.

At the end of the grant period, any credits that are still unused are expired. Fresh credits are granted for the new period. Overage credits already deducted in the closed period remain on that period's monthly addon invoice.

6. Be notified on credits and spends and take desired action

Use a Credits alert to watch the shared AI Credits balance, and a Spends alert to watch the dollar amount invoiced past the grant.

A Credits alert triggers when the prepaid credit balance for one credit unit drops to or below the amount you set. Each credit alert applies to a subscription and one credit unit. Credits is in early access and requires Prepaid Credits to be enabled. A Spends alert triggers when usage charges from metered addons exceed an amount you set. Chargebee counts only usage beyond the included entitlement. Other charges on the subscription are outside this threshold.

See Usage Alerts and Setting up Alerts.

6a. Create a Credits alert

A credit alert fires when the shared balance drops to or below a number of AI Credits. It is a site-level rule. Chargebee Billing evaluates it as ledger operations update the balance. The threshold is absolute, so the same alert fires at that floor on Growth and on Enterprise. An alert at 2,000 remaining AI Credits is an early signal, before overages start. An alert at 0 marks an empty grant.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="credit_balance_dropped" \
     -d name="AI credits low" \
     -d description="Notify when AI Credits drop to 2000" \
     -d unit_id="ai_credits" \
     -d "threshold[mode]"="absolute" \
     -d "threshold[value]"=2000

6b. Create a Spends alert

A spend alert fires when accrued overage charges on the On-demand AI Credits addon reach a dollar amount. The threshold is an absolute amount in the major units of the currency: 200 is $200. At $0.10 per AI Credit, $200 is 2,000 credits past the grant. The alert does not cap that spend. The addon still invoices every credit past the grant.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="spend_exceeded" \
     -d name="AI credits overage spend" \
     -d description="Notify when overage spend reaches 200 USD" \
     -d currency_code="USD" \
     -d "threshold[mode]"="absolute" \
     -d "threshold[value]"=200

6c. Take action when the threshold is reached

When a credit balance drops to the floor you set, or when overage spend reaches the amount you set, the alert status changes between within_limit and in_alarm. Chargebee sends an alert_status_changed webhook. Use that webhook to email the customer, show an upgrade prompt, or start another workflow. For example, when remaining AI Credits drop to 2,000, prompt an upgrade from Growth to Enterprise. When overage spend reaches $200, tell the customer that further credits are invoiced at $0.10 each.

7. Create the customer and subscription

With the catalog and the credit-balance alert in place, create the customer and their subscription. A customer record must exist before a subscription can be created. Create the subscription for Acme's contact, John Doe, on the Growth yearly plan, and attach the On-demand AI Credits monthly addon. The plan grant of 10,000 AI Credits per month is provisioned when the customer subscribes. Without the addon on the subscription, consumption past the grant is not invoiced.

To raise the grant for this subscription only, open the three-dot menu next to the plan and select Manage Credit Grants. Leave the credit unit unchanged. The override applies only to this subscription. The Growth default of 10,000 stays in place for every other customer. See Override credit grant settings for a specific subscription.

curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="John" \
     -d last_name="Doe" \
     -d email="jdoe@example.com"

curl  https://{site}.chargebee.com/api/v2/customers/{customer_id}/subscription_for_items \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="growth-USD-yearly" \
     -d "subscription_items[item_price_id][1]"="on-demand-ai-credits-USD-monthly"

Your active subscription looks like this:

8. Track usage against your subscriptions

Check the shared credit balance during the term. On Growth, the grant is 10,000 AI Credits each month. Credits past that grant accrue on the On-demand AI Credits addon until the monthly invoice is generated.

curl  https://{site}.chargebee.com/api/v2/ledger_account_balances \
     -G \
     -u {site_api_key}:\
     --data-urlencode "subscription_id[is]"="{subscription_id}" \
     --data-urlencode "unit_id[is]"="ai_credits"

Manage overage invoices

At the end of each monthly billing period, Chargebee Billing invoices the On-demand AI Credits addon for credits consumed past the grant. The customer is not charged an overage for credits that the monthly grant still covers.

Metered addon invoices are created in a Pending state. While an invoice is pending, it does not trigger payment collection. You manage how pending overage invoices close under Settings > Configure Chargebee > Billing LogIQ > Usage Based Billing. Two behaviors are available:

• Manual close. Review usage, then close the invoice yourself.
• Auto-close. Chargebee Billing closes the invoice automatically at a time you define.

Once an invoice is closed, payment collection begins. If you need to correct a closed invoice, void it and regenerate it.

See Actions for pending invoices.

Summary

This guide showed you how to:

• Define one AI Credits unit that article generation, image generation, and video generation share.
• Grant 10,000 credits each month on a $12,000 yearly Growth plan and 50,000 on a $30,000 yearly Enterprise plan, with unused credits expired at the end of the grant period.
• Attach a monthly metered addon that invoices AI Credits past the grant at $0.10 each.
• Set per-unit credit rates and send usage events so Chargebee deducts credits from the shared balance, then invoice the credits past the grant.

FAQs

Why didn't a usage event deduct credits?

Chargebee accepts the usage event and skips the deduction when the event timestamp is outside the current billing term and the grant-expiry grace period, the deduction would pass the allowed negative balance, the feature aggregation is not SUM or COUNT, the feature has included usage greater than 0, the feature has no credit rate in the subscription's credit unit, or the credit rate override is 0.

Do negative usage events add credits back?

No. A usage event with a negative quantity corrects the usage summary and does not return credits to the credit balance.

Can Chargebee block a customer when credits run out?

No. Usage events are processed after the product action. Gate access in your application from a credit-balance alert. Credits past the grant on this model are invoiced by the overage addon.