Prepaid credits: Offer shared credit pool and bill overages

Overview

If your business sells prepaid credits where every product draws from a common pool, and you invoice customers for overages beyond the grant, this guide shows you how to build that model in Chargebee Billing. You define one credit unit. Each plan grants a balance of that unit. Every product spends from the same balance, at its own rate. A metered addon invoices the credits consumed past the grant.

This guide is for billing administrators and developers who are implementing the model end-to-end in the Chargebee Billing app and with the API. See Usage-based billing use cases for other billing cadence combinations.

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. Article generation draws 1 AI Credit, image generation draws 10, and video generation draws 50. 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.

Use Prepaid credits: Offer shared credit pool for all the products when the balance should stop at zero and excess usage should not be invoiced. Use this guide when consumption past the grant should be invoiced.

Related use cases

• Prepaid credits: Offer shared credit pool for all the products
• Bill annually with annual included usage and monthly overages

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

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. Capture article, image, and video debits that stay inside the grant, then capture debits 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, captures, and credit-balance alerts all use this unit. Article generation, image generation, and video generation share it.

Consumption past the grant has to be allowed, or the overage addon has nothing to invoice. This example does not put a fixed cap on that consumption. The overage addon prices every AI Credit past the monthly grant.

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 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.

2a. 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}"

2b. 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

2c. 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.

3. 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.

3a. 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

3b. 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

4. Draw down the shared credit pool

When the customer uses a product, draw credits from the shared pool in one of two ways.

• Capture when you already know how many credits the action uses. Capture moves credits from the usable balance to consumed and writes an immutable ledger operation.
• Authorize, then capture when a job is still in progress and the final amount is not known yet. Authorize moves credits from the usable balance to a held amount. Other operations cannot spend held credits, and nothing is consumed yet. When the job finishes, Capture authorization converts the held credits into consumed credits. If the job used fewer credits than you reserved, capture only the amount used. The unused remainder returns to the usable balance. If the job is canceled, Release authorization returns the entire hold to the usable balance.

Pass amount as a decimal string. ledger_operation_timestamp is a Unix timestamp in seconds.

Compute the credit amount in your application, then send that amount to Chargebee Billing. Your application decides how many credits to draw from the ledger balance for each feature. For example, one article generation draws 1 AI Credit, one image generation draws 10 AI Credits, and one video generation draws 50 AI Credits.

Article generation, image generation, and video generation use the same credit unit, ai_credits. One article sends amount "1". One image sends amount "10". One video sends amount "50". Each call draws from the same balance. The plan only changes how many credits were granted.

Credits within the monthly grant are covered by the plan fee. With is_unlimited set to true on the credit unit, Capture 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.

curl  https://{site}.chargebee.com/api/v2/ledger_operations/capture \
     -u {site_api_key}:\
     -d id="op-image-0001" \
     -d subscription_id="{subscription_id}" \
     -d unit_id="ai_credits" \
     -d amount="10" \
     -d ledger_operation_timestamp=1737612931

curl  https://{site}.chargebee.com/api/v2/ledger_operations/authorize \
     -u {site_api_key}:\
     -d id="op-image-0001-hold" \
     -d subscription_id="{subscription_id}" \
     -d unit_id="ai_credits" \
     -d amount="10" \
     -d ledger_operation_timestamp=1737612931 \
     -d auto_release_timestamp=1737616531

curl  https://{site}.chargebee.com/api/v2/ledger_operations/capture_authorization \
     -u {site_api_key}:\
     -d id="op-image-0001-capture" \
     -d authorization_id="op-image-0001-hold" \
     -d amount="10" \
     -d ledger_operation_timestamp=1737613200

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 captured in the closed period remain on that period's monthly addon invoice.

5. Take action on a defined threshold using alerts

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

Create credit alerts

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

Create spend alerts

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

Be notified 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.

6. 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 company="Acme Inc." \
     -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:

7. Monitor prepaid credits and overages during the term

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.
• Draw all three products from the same ledger with Capture, or with Authorize followed by Capture authorization, read the usable balance, and use a credit alert and a spend alert before overages grow.

FAQs

How do I make sure a customer has enough credits before starting a job, without other requests spending the same credits?

Call Authorize. It reserves the credits by moving them from the usable balance to a held amount. Other operations cannot spend held credits, so concurrent requests cannot spend the same credits in the meantime. Nothing is consumed at this stage.

Use Authorize while a job is still in progress and the final amount is not known yet. When you already know how many credits to draw, call Capture.

How do I reserve credits when a job starts and consume them only when it completes?

Call Authorize when the job starts to hold the credits. When the job finishes, call Capture authorization to convert the held credits into consumed credits. If the job used fewer credits than you reserved, capture only the amount used. The unused remainder is automatically released back to the usable balance.

For example, authorize 100 credits, and the job uses 70. Capture 70. Result: 70 credits are consumed, and 30 are released.

The customer canceled, or my process failed after I reserved credits. How do I give the credits back?

Call Release authorization with the authorization_id from the original Authorize operation. The entire held amount returns to the usable balance, and nothing is consumed. Partial releases are not supported.

What happens if I authorize credits and never capture or release them?

The hold is automatically released back to the usable balance when it expires. By default this is about 10 minutes after the Authorize request is processed. You can set a different expiration with auto_release_timestamp.

See also

• Usage-based billing use cases
• Prepaid credits: Offer shared credit pool for all the products
• Prepaid credits
• Configure overage pricing
• Multi-Frequency Billing
• Usage Alerts
• Show prepaid credit balances, grants, and transactions in your customer portal
• Credit units API
• Ledger operations API