Bill customers purely based on usage at a fixed price per unit

Overview

Some products have no platform fee and no included quota: customers pay only for what they use, with no monthly minimum or upfront commitment. This guide shows you how to build that pay-as-you-go (PAYG) model in Chargebee Billing: a $0 monthly plan that holds the subscription, paired with a monthly metered addon that bills every unit consumed.

Throughout this guide, you configure the model for a single running example. Acme Inc. offers a free-to-start tier with no monthly minimum. John Doe signs up on the Platform plan: $0 per month, with no included file uploads. Every file upload is invoiced monthly at $0.05. If John uploads 50,000 files in January, the February 1 invoice is $2,500.

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.

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 all recorded file uploads are rated at $0.05 and that a month with zero file uploads generates no metered charge.

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

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

You can start sending raw usage before finalizing rates. Track adoption patterns over time, then use those insights to define the metered feature and per-unit 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-upload-0001",
     "subscription_id": "{subscription_id}",
     "usage_timestamp": "1737612931000",
     "properties": {
          "number_of_file_uploads": 12,
          "file_id": "file_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-upload-0001",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612931000",
               "properties": {
                    "number_of_file_uploads": 12
               }
          },
          {
               "deduplication_id": "usage-upload-0002",
               "subscription_id": "{subscription_id}",
               "usage_timestamp": "1737612991000",
               "properties": {
                    "number_of_file_uploads": 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 file uploads, 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 File Uploads with the aggregation method SUM on the number_of_file_uploads 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="File Uploads" \
     -d feature_unit="file_upload" \
     -d description="Number of file uploads consumable." \
     -d query="SELECT SUM(number_of_file_uploads) from events" \
     -d "column_definitions[column_name][0]"="number_of_file_uploads" \
     -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.

3a. Create the plan

Create a Platform plan that acts as the subscription container, and link pricing to the plan in the next step.

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}: \
     -d id="platform" \
     -d name="Platform" \
     -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="platform-USD-monthly" \
     -d item_id="platform" \
     -d name="Platform 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 for usage

Metered addons are catalog items that let you measure and rate metered features. In this model, the addon bills customers for every file upload consumed — there is no plan quota to exhaust first. Entitlements on metered addons are unlimited by default, so every recorded unit is billable.

4a. Create the addon

curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}: \
     -d id="on-demand-file-uploads" \
     -d name="On-demand File Uploads" \
     -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]"="file-uploads" \
     -d "entitlements[entity_id][0]"="on-demand-file-uploads" \
     -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 where you define how the file uploads are rated.

curl  https://{site}.chargebee.com/api/v2/item_prices \
     -u {site_api_key}: \
     -d id="on-demand-file-uploads-USD-monthly" \
     -d item_id="on-demand-file-uploads" \
     -d name="On-demand File Uploads USD monthly" \
     -d pricing_model="PER_UNIT" \
     -d price=5 \
     -d currency_code="USD" \
     -d period_unit="MONTH" \
     -d period=1

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 file-upload charges exceed $500.

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

Take action when the threshold is reached

When accrued charges exceed $500, 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 file uploads 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, John Doe, on the $0 monthly plan, and attach the metered addon so every file upload is invoiced at period end.

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]"="platform-USD-monthly" \
     -d "subscription_items[item_price_id][1]"="on-demand-file-uploads-USD-monthly"

Your active subscription looks like this:

7. Track usage against your subscriptions and share with customers

Use the following options to monitor file uploads 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_summary \
     -G \
     -u {site_api_key}: \
     --data-urlencode feature_id="file-uploads"

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

Review usage after invoicing

Related use cases

Move to a hybrid plan with included usage

PAYG customers have no upfront commitment, so they can churn. When a customer is ready for a monthly minimum and a usage quota, change the subscription to a plan that grants included usage and keep the metered addon for overages.

For the full proration and entitlement behavior when the plan change happens mid-term, see Mid-term subscription changes. For how to configure the hybrid catalog itself, see Included Usage Billing and overage pricing models.

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.

Cancel a PAYG subscription

Summary

This guide showed you how to:

• Turn raw usage into a metered feature, then configure a $0 monthly plan with no included usage and a monthly addon that bills every unit.
• Create the subscription, monitor usage and spend alerts, move a customer onto a hybrid plan, and validate a monthly cycle with Time Machine.