Prepaid credits: Offer shared credit pool for all the products

Overview

If your business uses fully prepaid pricing, where your customer buys credits and uses them for all of their products, this guide shows you how to build this 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. Your application cuts off access or tops up when the shared balance is exhausted.

This guide is the implementation companion to the Prepaid credits with rollovers recipe for billing administrators and developers who are implementing it end-to-end in the Chargebee Billing app and with the API. See Usage-based billing use cases for other billing cadence combinations. Use Offer included usage with a hard cap when each product has its own included quantity as a metered-feature entitlement, rather than a shared credit balance.

Field-level setup for credit units, grant versions, and overage addons is in Prepaid credits. This guide walks one commercial model from catalog to subscription.

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, image generation, and video generation all draw from that balance. Enterprise is $30,000 per year, with 50,000 AI Credits granted each month. Unused credits expire at the end of the grant period.

How this billing model works

The illustration below explains how this billing model works:

Before you start

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.

Prepaid Credits feature 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, confirm the monthly grant of 10,000 AI Credits, capture an article-generation debit, an image-generation debit, and a video-generation debit, and advance to the next grant date so you can see unused credits roll forward and credits older than one month expire.

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 customers spend. Create it once. Grants, captures, 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"

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. Draw down the shared credit pool

When the customer uses a product, capture credits immediately. Capture moves credits from the usable balance to consumed and writes an immutable ledger operation. 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. Chargebee Billing does not convert product usage events into credits. 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. Send that credit value with the Capture API.

Article generation, image generation, and video generation call the same capture endpoint with unit_id set to ai_credits. One article sends amount "1". One image sends amount "10". One video sends amount "50". Each call reduces the same usable balance. The plan only changes how many credits were granted.

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

At the end of the grant period, any credits that are still unused are expired. Fresh credits are granted for the new period.

4. Restrict usage within a cap using site-level thresholds

Create the credit-balance alert before customers can exhaust the pool. A credit-balance alert is a site-level rule. Chargebee Billing evaluates it as ledger operations update the balance. The threshold is an absolute number of AI Credits, so the same alert fires at that floor on Growth and on Enterprise.

4a. Create a credit-balance alert for the shared pool

Create a credit_balance_dropped alert on ai_credits. The threshold mode is absolute: the alert fires when the credit balance for that unit drops to or below the value you set. An alert at 0 marks an empty pool for every plan. A second alert at 2,000 remaining AI Credits is an earlier signal. Because the threshold is absolute, 2,000 remaining is a larger share of Growth's 10,000 than of Enterprise's 50,000.

Credit-balance alerts deliver the webhook this model uses when the shared balance reaches the floor you set. Create that alert with the Alerts API. Usage alerts for metered features are available in the app under Usages > Alerts. See Usage Alerts. Configure a webhook endpoint under Settings > Configure Chargebee > API Keys and Webhooks, on the Webhooks tab, before you rely on alert_status_changed. See Webhook Settings.

Credit-balance alerts are evaluated as ledger operations update the balance. When the status changes between in_alarm and within_limit, Chargebee sends an alert_status_changed webhook. Your endpoint then cuts off access.

Usage alerts for metered features are created in the app. Go to Usages > Alerts and click Create Alert. See Setting up usage alerts. Create this credit-balance alert with the API.

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

4b. Take action when the threshold is reached

The grant is a balance Chargebee Billing can measure and alert on. It does not, by itself, stop the customer from using article generation, image generation, or video generation. Your application enforces the commercial response.

Use a credit_balance_dropped alert at 0. When alert_status_changed reports in_alarm, your application rejects the next article, image, or video, and stops calling capture for that subscription.

Chargebee Billing keeps accepting capture calls after the balance is exhausted and does not enforce this stop inside your product. If the customer can still use a product, your application will keep submitting capture calls. With Allowed negative balance left blank, capture is evaluated against the usable balance, so a debit larger than the remaining credits does not silently extend the grant. Units beyond the grant are outside the plan fee. Check provisioned_balance.usable_balance before you start the action. If the balance does not cover the credits that action draws, block the action in your product. On Growth, that balance starts at 10,000 AI Credits. On Enterprise, it starts at 50,000.

5. 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. The plan grant of 10,000 AI Credits per month is provisioned when the customer subscribes. Do not attach a metered addon.

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"

Your active subscription looks like this:

6. Monitor prepaid credits during the term

Check the shared credit balance during the term. On Growth, the grant is 10,000 AI Credits each month.

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"

Decide what happens when prepaid credits are exhausted

This guide's primary path is a fully prepaid access cut-off. When a credit-balance alert at 0 changes to in_alarm, your application cuts off article generation, image generation, and video generation and stops calling capture. Chargebee Billing measures the shared balance and sends the alert_status_changed webhook. You can take an action to stop product usage with a webhook event.

You can offer another commercial response instead of, or alongside, that cut-off:

• Upgrade. Move the customer to a plan with a larger monthly grant, such as from Growth to Enterprise. See Changing a plan or prepaid addon mid-term.
• Top-up. Add credits with a charge or non-metered addon that has its own credit grant. See Prepaid credits.
• Overage pricing. Attach a metered addon set to bill overage for the AI Credits grant, and invoice consumption past the grant. See Configure overage pricing.

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 rolling forward for one month.
• Capture all three products on the same ledger, read the usable balance, and use a site-level credit-balance alert to cut off access when the pool is exhausted.

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 included usage with a hard cap
• Usage Alerts
• Show prepaid credit balances, grants, and transactions in your customer portal
• Credit units API
• Ledger operations API