Bill customers purely based on usage by package, not by individual unit

Overview

Some products sell usage in blocks rather than single units. The price is a rate per package, and any usage that does not fill a package still consumes a whole package. This guide shows you how to build that model in Chargebee Billing with Package Pricing on metered addons.

Throughout this guide, you configure one running example. Acme Inc. charges $0.50 for every 1,000,000 input tokens and $1.50 for every 1,000,000 output tokens. Jordan Lee subscribes to a $0 monthly plan that holds the subscription, plus two monthly metered addons. Each addon uses volume pricing with one open tier and a package size of 1,000,000.

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.

Enable Package Pricing on your site before you set a package size.

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 a full monthly cycle on a test site. You can test your billing setup in Chargebee's test site using Time Machine. Advance from subscription creation through usage ingestion to the first renewal so you can confirm that input token totals round up to whole packages of 1,000,000 at $0.50, and output token totals round up to whole packages of 1,000,000 at $1.50.

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 invoice 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 token usage into Chargebee Billing. For Acme, one usage event is generated for each model request, and it includes an input_tokens property and an output_tokens property.

Chargebee's ingestion is schemaless. You can start sending raw usage before finalizing rates. Track adoption patterns over time, then use those insights to define the metered features and package prices.

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": "tokens-0001",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "input_tokens": 1200,
          "output_tokens": 350,
          "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": "tokens-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612931000",
               "properties": {
                    "input_tokens": 1200,
                    "output_tokens": 350
               }
          },
          {
               "deduplication_id": "tokens-0002",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612991000",
               "properties": {
                    "input_tokens": 800,
                    "output_tokens": 200
               }
          }
     ]
}'

2. Define the unit of value your product delivers

Now that usage is flowing, decide what feature(s) or product(s) you offer 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 one 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 two metered features. Input Tokens uses the aggregation method Sum on the input_tokens property. Output Tokens uses Sum on the output_tokens property.

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Input Tokens" \
     -d feature_unit="input_token" \
     -d description="Number of input tokens consumed." \
     -d query="SELECT SUM(input_tokens) FROM events" \
     -d "column_definitions[column_name][0]"="input_tokens" \
     -d "column_definitions[data_type][0]"="number"

curl  https://{site}.chargebee.com/api/v2/metered_features \
     -u {site_api_key}:\
     -d name="Output Tokens" \
     -d feature_unit="output_token" \
     -d description="Number of output tokens consumed." \
     -d query="SELECT SUM(output_tokens) FROM events" \
     -d "column_definitions[column_name][0]"="output_tokens" \
     -d "column_definitions[data_type][0]"="number"

3. Package your offerings into a plan

This step creates a $0 monthly plan that holds the subscription. There is no included usage on this plan and every usage is billed based on block consumption.

3a. Create the plan

Create a Standard Model plan that acts as the subscription container.

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="standard-model" \
     -d name="Standard Model" \
     -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="standard-model-USD-monthly" \
     -d item_id="standard-model" \
     -d name="Standard Model USD monthly" \
     -d pricing_model="flat_fee" \
     -d price=0 \
     -d currency_code="USD" \
     -d period_unit="month" \
     -d period=1

4. Define how to charge your packaged usages

Metered addons are catalog items that let you measure and rate metered features. In this model, one addon bills input tokens in packages of 1,000,000 at $0.50, and a second addon bills output tokens in packages of 1,000,000 at $1.50. Entitlements on metered addons are unlimited by default, so every recorded token is included in the package count for its feature.

Create Input Token Packages first, then repeat the same steps for Output Token Packages.

4a. Create the addon

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="input-token-packages" \
     -d name="Input Token Packages" \
     -d type="ADDON" \
     -d item_family_id="{item_family_id}" \
     -d metered=true

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="output-token-packages" \
     -d name="Output Token Packages" \
     -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]"="Input-Tokens" \
     -d "entitlements[entity_id][0]"="input-token-packages" \
     -d "entitlements[entity_type][0]"="ADDON" \
     -d "entitlements[value][0]"="unlimited"

curl  https://{site}.chargebee.com/api/v2/entitlements \
     -u {site_api_key}:\
     -d action="UPSERT" \
     -d "entitlements[feature_id][0]"="Output-Tokens" \
     -d "entitlements[entity_id][0]"="output-token-packages" \
     -d "entitlements[entity_type][0]"="ADDON" \
     -d "entitlements[value][0]"="unlimited"

4b. Set the package size and package price

Package Pricing must already be enabled on the site. On each addon price, select Allow advanced pricing configurations for this item, set Pricing model to Volume, and define one open tier.

Both addons use the same package size. The package price is different for each token type.

In the app, the price column is labeled Price per unit. When Pricing Type is Package, that amount is the price of one package, not the price of one token.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="input-token-packages-USD-monthly" \
     -d item_id="input-token-packages" \
     -d name="Input Token Packages USD monthly" \
     -d pricing_model="volume" \
     -d currency_code="USD" \
     -d period_unit="month" \
     -d period=1 \
     -d "tiers[starting_unit][0]"=1 \
     -d "tiers[price][0]"=50 \
     -d "tiers[pricing_type][0]"="package" \
     -d "tiers[package_size][0]"=1000000

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}:\
     -d id="output-token-packages-USD-monthly" \
     -d item_id="output-token-packages" \
     -d name="Output Token Packages USD monthly" \
     -d pricing_model="volume" \
     -d currency_code="USD" \
     -d period_unit="month" \
     -d period=1 \
     -d "tiers[starting_unit][0]"=1 \
     -d "tiers[price][0]"=150 \
     -d "tiers[pricing_type][0]"="package" \
     -d "tiers[package_size][0]"=1000000

5. Be notified on spends and take desired action

A Spends alert watches usage charges from metered addons and triggers when those charges exceed an amount you set. See Setting up Alerts.

Create a Spends alert

This example fires when accrued token-package charges exceed $10.

curl  https://{site}.chargebee.com/api/v2/alerts \
     -u {site_api_key}:\
     -d type="spend_exceeded" \
     -d name="Token package spend 10" \
     -d description="Notify when token package spend crosses 10 USD" \
     -d currency_code="USD" \
     -d "threshold[mode]"="absolute" \
     -d "threshold[value]"=10

Take action when the threshold is reached

When accrued charges exceed the amount you set, the alert status changes from within_limit to in_alarm, and Chargebee sends an alert_status_changed webhook. Use that webhook to email the customer, show an in-app prompt, or pause further token usage in your product. Chargebee Billing records the usage and does not enforce that stop.

6. 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, Jordan Lee, on the $0 monthly plan, and attach both metered addons.

curl  https://{site}.chargebee.com/api/v2/customers \
     -u {site_api_key}:\
     -d first_name="Jordan" \
     -d last_name="Lee"

curl  https://{site}.chargebee.com/api/v2/customers/{customer_id}/subscription_for_items \
     -u {site_api_key}:\
     -d "subscription_items[item_price_id][0]"="standard-model-USD-monthly" \
     -d "subscription_items[item_price_id][1]"="input-token-packages-USD-monthly" \
     -d "subscription_items[item_price_id][2]"="output-token-packages-USD-monthly"

Your active subscription looks like this:

7. Track usage against your subscriptions and share with customers

Use the following options to monitor input token and output token totals during the current term, review charges after invoicing, and answer customer questions about their invoice.

Monitor usage during the current period

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

Review usage after invoicing and share details with customers

Manage usage invoices

At the end of each monthly billing period, Chargebee Billing creates the usage 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 usage 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.

Summary

This guide showed you how to:

• Turn raw token events into two metered features, Input Tokens and Output Tokens, then rate input tokens at $0.50 per package of 1,000,000 and output tokens at $1.50 per package of 1,000,000.
• Put a $0 monthly plan on the subscription and attach two volume-priced metered addons, each with a package size of 1,000,000.
• Create the subscription, confirm round-up on a test site with Time Machine, and close the pending usage invoice.