Offer prepaid credits shared across products and manage customer credit balances directly, without sending usage data

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 with the direct credit ledger. You define one credit unit. Each plan grants a balance of that unit. Your application calculates how many credits each action costs and sends that number to Chargebee. Your application cuts off access or tops up when the shared balance is exhausted.

Use Offer prepaid credits that customers spend across your products at different rates when Chargebee should convert usage events into credits.

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

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.

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 expired at the end of previous grant period.

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, draw credits from the shared pool in one of two ways.

• Capture when you already know how many credits the action uses and you can draw them in one step. Capture is a direct draw: it moves credits from the usable balance to consumed and writes an immutable ledger operation.
• Authorize, then capture when the final amount is unknown while a job is in progress, or when several operations or users draw from the same pool at the same time. Authorize blocks those credits during a synchronous operation to prevent overuse or abuse. Authorize holds the credits when the job begins by moving them 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.

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.

4. Define credit alerts and be notified

A Credits alert triggers when the prepaid credit balance for one credit unit drops to or below the amount you set.

Create the credit-balance alert before customers can exhaust the pool. A Credits 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 Credits alert

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

Usages alerts for metered features use the same Usages > Alerts page. The API example below creates this credit-balance alert with credit_balance_dropped.

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 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. Track usage against your subscriptions

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 Sell annual plans that grant included usages every month used across products and charge overage monthly.

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.
• Draw all three products from the same ledger with Capture, or with Authorize followed by Capture authorization, 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, then capture when the final amount is unknown while a job is in progress, or when several operations or users draw from the same pool at the same time. Authorize blocks the credits during that synchronous operation to prevent overuse or abuse. When you already know the amount and you can draw it in one step, 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.