Prepaid included usage: Offer separate usage grant for each product with a hard cap

Overview

If your business uses fully prepaid pricing, where your customer gets a specific included usage limit for each product with the plan, this guide shows you how to build this model in Chargebee Billing. You define each product as a metered feature, link it to the plan, and set the included usage the customer is entitled to when they buy the plan. Your application can cut off access to that product or top up when the limit is reached.

This is the implementation companion to the Included usage with hard caps 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.

Throughout this guide, you configure the model for a single running example. Acme Inc. sells two monthly plans. Both grant included usage for API Calls, Storage, and Messages. The quantities differ by plan:

John Doe subscribes to Growth on January 1: $99 per month, with 50,000 API calls, 50 GB of storage, and 10,000 messages included. The $99 invoice is the full charge for that term. Crossing any quota does not create an overage invoice. Enterprise is a higher monthly flat fee, with 200,000 API calls, 200 GB of storage, and 40,000 messages.

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.

Validate before go-live

Before enabling this on a live site, validate one full monthly cycle on a test site with Time Machine. Create a Growth subscription, ingest usage below the included API calls, storage, and messages, then ingest usage that crosses 50,000 API calls, 50 GB, or 10,000 messages. Confirm that the usage summary shows the totals.

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. Send usage into Chargebee Billing

Start by streaming your product's usage into Chargebee Billing before you have finalized the included quotas. For Acme, a usage event is generated every time an API call is made, and it includes a number_of_api_calls property. A separate event records storage, and it includes a storage_gb property. A third event records messages sent, and it includes a number_of_messages property. For your business, this could be words processed, image generations, file uploads, or data stored.

Chargebee's ingestion is schemaless. This example meters API calls, storage, and messages. You can track additional properties on the same event and decide later which of them to price.

You can add any additional properties relevant to your product, such as request_id or user_id. Chargebee Billing stores them alongside the required attributes, deduplicates repeated events, and keeps the raw stream queryable.

You can send usage in one of the following ways, based on how your product emits usage:

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": "usage-api-0001",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "number_of_api_calls": 12,
          "request_id": "req_1001"
     }
}'

curl  https://{site}.ingest.chargebee.com/api/v2/batch/usage_events \
     -u {site_api_key}:\
     --header 'Content-Type: application/json;charset=UTF-8' \
     --data '{
     "events": [
          {
               "deduplication_id": "usage-api-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612931000",
               "properties": {
                    "number_of_api_calls": 12
               }
          },
          {
               "deduplication_id": "usage-msg-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612991000",
               "properties": {
                    "number_of_messages": 3
               }
          }
     ]
}'

2. Define the unit of value your product delivers

Now that usage is flowing, decide what you will include in the plan. In Chargebee Billing, you capture that unit by defining a metered feature.

A metered feature tells Chargebee how to aggregate raw events into a single number for each period. You set the aggregation rule on the feature, and from that point Chargebee rolls up matching events against it.

For Acme, create three metered features. API Calls uses the aggregation method SUM on the number_of_api_calls property. Storage uses SUM on the storage_gb property. Messages uses SUM on the number_of_messages property. The steps below walk through API Calls. Repeat them for Storage and Messages.

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="API Calls" \
     -d feature_unit="api_call" \
     -d description="Number of API calls included in the plan." \
     -d query="SELECT SUM(number_of_api_calls) from events" \
     -d "column_definitions[column_name][0]"="number_of_api_calls" \
     -d "column_definitions[data_type][0]"="NUMBER"

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Storage" \
     -d feature_unit="gb" \
     -d description="Storage included in the plan, in gigabytes." \
     -d query="SELECT SUM(storage_gb) from events" \
     -d "column_definitions[column_name][0]"="storage_gb" \
     -d "column_definitions[data_type][0]"="NUMBER"

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Messages" \
     -d feature_unit="message" \
     -d description="Messages included in the plan." \
     -d query="SELECT SUM(number_of_messages) from events" \
     -d "column_definitions[column_name][0]"="number_of_messages" \
     -d "column_definitions[data_type][0]"="NUMBER"

3. Define the included quotas for your plans

This step creates the monthly plans, sets their prices, and defines how much API usage, storage, and messages each plan includes.

3a. Create the plans

Create Growth and Enterprise. Each plan carries its own monthly platform fee. You link pricing and the included quotas 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 monthly price point for it. Growth is $99. Enterprise uses the same flat-fee model at a higher monthly price.

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

3c. Link the metered features and set included usage

Link API Calls, Storage, and Messages to both plans and set the included quantity on each. These entitlements are the hard caps for the billing period.

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[feature_id][0]"="api-calls" \
     -d "entitlements[entity_id][0]"="growth" \
     -d "entitlements[entity_type][0]"="PLAN" \
     -d "entitlements[value][0]"="50000"

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

4a. Create a usage alert for the included quota

Create the usage alerts before customers can reach a ceiling. A usage alert is a site-level rule. Chargebee Billing evaluates it as usage events are processed. A percentage threshold follows the included usage on each subscription, so the same alert fires at 50,000 API calls on Growth and at 200,000 API calls on Enterprise.

Usage alerts deliver the webhook this model uses when a customer approaches or reaches an included quota. Configure a webhook endpoint under Settings > Configure Chargebee > API Keys and Webhooks, on the Webhooks tab. See Usage Alerts.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="usage_exceeded" \
     -d name="API calls 80 percent" \
     -d description="Notify when API calls cross 80 percent of included usage" \
     -d metered_feature_id="api-calls" \
     -d "threshold[mode]"="percentage" \
     -d "threshold[value]"=80

4b. Take action when the threshold is reached

The included entitlement is a quota Chargebee Billing can measure and alert on. It does not, by itself, stop the customer from using your product. Your application enforces the commercial response. Pick one response, or combine them. For example, warn at 80 percent, offer an upgrade, and cut off access at 100 percent.

Use a usage_exceeded alert at 100 percent of included usage. When alert_status_changed reports in_alarm, your application rejects the next product action and stops sending usage events for that subscription.

Chargebee Billing keeps accepting usage events after the quota is exhausted and does not enforce this stop. Access control lives in your product. If the customer can still use the product, your application will keep ingesting events, and the running total will move past the included quota. On Growth, that quota is 50,000 API calls, 50 GB of storage, or 10,000 messages. Those additional units are not covered by the plan fee. If the subscription later has a metered addon, Chargebee Billing bills them as overages. If you intend a hard stop, block the product action first, then stop ingestion.

Check remaining usage with Retrieve usage summary for a subscription before you accept a request, so a single large request cannot land after the quota is already exhausted.

5. Create the customer and subscription

With the catalog in place, create the customer and their subscription. A customer record must exist before a subscription can be created. You can create it first, or create both together in the same flow. Create the subscription for Acme's contact, John Doe, on the Growth monthly plan. Do not attach a metered addon.

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-monthly"

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/entitlement_overrides \
     -X POST \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlement_overrides[feature_id][0]"="api-calls" \
     -d "entitlement_overrides[value][0]"="80000"

Your active subscription looks like this:

6. Monitor included usage during the term

Check consumed usage against the included quotas during the term. On Growth, those quotas are 50,000 API calls, 50 GB of storage, and 10,000 messages.

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usage_summary \
     -G \
     -u {site_api_key}:\
     --data-urlencode feature_id="api-calls"

Decide what happens when included usage is exhausted

This guide's primary path is a fully prepaid hard cap. When a usage alert at 100 percent of included usage changes to in_alarm, your application cuts off access and stops sending usage events. Chargebee Billing measures the quota 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 included quota, such as from Growth to Enterprise. See Changing a plan or prepaid addon mid-term.
• Top-up. Grant more included usage for the current term with a non-metered addon. See Top-up of entitlements mid-term.
• Overage pricing. Attach a metered addon and invoice units beyond the included quota. See Bill annually with annual included usage and monthly overages.

Summary

This guide showed you how to:

• Turn raw usage into metered features and grant different included quantities on flat-fee plans.
• Subscribe a customer without a metered addon, so each included quantity is a ceiling rather than the start of an overage invoice.
• Use a site-level usage alert and the alert_status_changed webhook to cut off access when included usage is exhausted.

See also

• Usage-based billing use cases
• Prepaid credits with rollovers
• Bill annually with annual included usage and monthly overages
• Usage Alerts
• Usage Events API