Bill annually with annual included usage and monthly overages

Overview

Longer-term contracts are often prepaid annually for the platform fee, but overages still need to be invoiced as they happen so billing stays aligned with consumption. This guide shows you how to build that hybrid model in Chargebee Billing: an annual plan that grants a full-year usage quota, paired with a monthly metered addon that bills every unit consumed beyond the quota.

This is the implementation companion to the Included usage with overages 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. signs an annual contract on the Professional plan: $490 per year, with 10,000 image generations included for the year. If Acme exceeds 10,000 image generations during the annual term, the excess is invoiced monthly at $0.10 per image generation.

How this billing model works

The model depends on one subscription holding items that bill on two different cadences. The illustration below explains how this billing model works:

Before you start

The following settings are enabled by default for new Chargebee Billing sites. If you are an existing user, enable these features before you build the model:

• Advanced Usage-Based Billing
• Multi-Frequency Billing

Validate before go-live

Before enabling this on a live site, validate the full annual cycle on a test site. You can test your billing setup in Chargebee's test site using Time Machine. A test site offers a one-year Time Machine option, which is enough to validate a full annual subscription cycle end-to-end, from the initial annual invoice through monthly overages to renewal.

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've decided what to charge for. For Acme, a usage event is generated every time an image is generated, and it includes a number_of_image_generations property. For your business, this could be an API call, a file upload, a message sent, data storage, and so on.

Chargebee's ingestion is schemaless. While this example uses the number of image generations as the value metric, you can track usage for additional parameters as required for your business.

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

You can start sending raw usage before finalizing included quotas or overage rates. Track adoption patterns over time, then use those insights to define the metered feature, included quota, and overage pricing.

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-img-0001",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "number_of_image_generations": 12,
          "image_generation_id": "img_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-img-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612931000",
               "properties": {
                    "number_of_image_generations": 12
               }
          },
          {
               "deduplication_id": "usage-img-0002",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612991000",
               "properties": {
                    "number_of_image_generations": 8
               }
          }
     ]
}'

2. Define the unit of value your product delivers

Now that usage is flowing, decide what you'll actually charge for — the unit of value your product delivers, whether that's pages, API calls, image generations, or any other metric. In Chargebee Billing, you capture that unit by defining a metered feature.

A metered feature tells Chargebee how to aggregate your raw events into a single billable 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 a metered feature named Image Generations with the aggregation method SUM on the number_of_image_generations property. From this point, Chargebee aggregates matching events against the feature.

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Image Generations" \
     -d feature_unit="image_generation" \
     -d description="Number of image generations consumable." \
     -d query="SELECT SUM(number_of_image_generations) from events" \
     -d "column_definitions[column_name][0]"="number_of_image_generations" \
     -d "column_definitions[data_type][0]"="NUMBER"

3. Package your offerings into a plan

This step establishes the annual plan, sets its price point, and defines how many image generations are included for the year.

3a. Create the plan

Create a Professional plan that carries the prepaid annual platform fee, and link pricing to the plan in the next step.

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

3b. Define the plan price point

Once the plan is saved, create a price point for it.

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

3c. Grant features and define included usage

Link the Image Generations metered feature you created in Step 2 and set the included usage.

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

4. Define how to measure overages

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 customers for every image generation consumed after their annual included quota of 10,000 image generations is exhausted.

4a. Create the addon

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="on-demand-image-generations" \
     -d name="On-demand Image Generations" \
     -d type="ADDON" \
     -d item_family_id="{item_family_id}" \
     -d metered=true

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[feature_id][0]"="image-generations" \
     -d "entitlements[entity_id][0]"="on-demand-image-generations" \
     -d "entitlements[entity_type][0]"="ADDON" \
     -d "entitlements[value][0]"="unlimited"

4b. Define the addon price point

Once the addon is created, create a monthly price point for it.

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

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 annual plan, and attach the metered addon so overages can be invoiced monthly while the plan fee stays annual.

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]"="professional-USD-yearly" \
     -d "subscription_items[item_price_id][1]"="on-demand-image-generations-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]"="image-generations" \
     -d "entitlement_overrides[value][0]"="15000"

Your active subscription looks like this:

6. Usage visibility and alerts

Use the following options to monitor usage, review billed consumption, and act before customers exceed their limits.

Monitor usage during the current term

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

curl  https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usage_charges \
     -u {site_api_key}:

Review usage after invoicing

Configure usage and spend alerts

Set alerts in Chargebee Billing and connect them to webhooks to automate downstream actions. For example, when a free-plan customer reaches 100%, you can block access and show an upgrade prompt.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="USAGE_EXCEEDED" \
     -d name="Image generations 75 percent" \
     -d description="Notify when usage crosses 75 percent of the annual quota" \
     -d metered_feature_id="image-generations" \
     -d "threshold[mode]"="PERCENTAGE" \
     -d "threshold[value]"=75 \
     -d "filter_conditions[field][0]"="PLAN_PRICE_ID" \
     -d "filter_conditions[operator][0]"="EQUALS" \
     -d "filter_conditions[value][0]"="professional-USD-yearly"

Related use cases

Manage upgrades, downgrades, and cancellations

Subscriptions on this model can change over time; customers move tiers or cancel. For upgrades and downgrades, Chargebee Billing prorates the new plan price based on the time remaining in the billing period. In every plan change, the remaining entitlements from the current plan are added to the full entitlements granted by the new plan.

For an upgrade or downgrade at the end of the term, schedule the change using Subscription Ramps. The current plan remains unchanged until renewal, when the new plan, price, and entitlements take effect automatically. You can also use ramps to schedule other future subscription changes, such as planned price increases.

For the full proration and entitlement behavior, see Mid-term subscription changes.

Add a usage top-up

To grant extra included usage without changing the plan, create a $0 non-metered addon that entitles the same metered feature, then set its billing cycles to 1 when you attach it to the subscription so that it does not recur. One-time charges cannot grant included usage; the addon is what increases the quota. For accurate revenue recognition, collect the top-up fee with a one-time charge.

Attaching a $50 yearly addon in November would prorate that $50. A one-time charge can collect $50 in full, but it cannot grant the extra quota. Split the purchase into two line items:

Manage overage invoices

At the end of each monthly billing period, Chargebee Billing creates the overage invoice in a Pending state. While an invoice is pending, you can still ingest usage events dated within the accepted backdating window, and they're included in the final charge. Pending invoices don't 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 all usage, then close the invoice yourself.
• Auto-close. Chargebee Billing closes the invoice automatically at a time you define.

Once an invoice is closed, no further usage can be added to it, and payment collection begins. If you need to correct a closed invoice, void it and regenerate it with the updated usage.

See Actions for pending invoices, the Invoices API, and the Credit Notes API.

Offer a trial period with specific included usage

Create a separate trial plan for the required duration and define custom entitlements for that period. Initially, the subscription holds this trial plan. At the end of one billing cycle, automatically update the subscription to the Professional yearly plan. You can schedule that change with Subscription Ramps.

Summary

This guide showed you how to:

• Turn raw usage into a metered feature, then configure an annual plan with included usage and a monthly addon for overages.
• Create the subscription, monitor usage and alerts, manage billing changes, and validate the complete cycle with Time Machine.

See also

• Usage-based billing use cases
• Understanding usages
• Multi-Frequency Billing
• Usage Alerts
• Usage Events API