Bill only for what customers use with pay-as-you-go pricing
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.
See Usage-based billing use cases for other usage-based billing models.
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
Although customers are charged purely based on usage, this model requires a subscription that holds a $0 monthly plan and a monthly metered addon. There is no included quota, so Chargebee Billing bills all recorded usage based on the price of the metered addon. The illustration below explains how this billing model works:
Before you start
Note
Confirm your access. You need an admin role to change site configuration and build the Product Catalog.
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.
Note
When you enter Time Machine, existing subscriptions and customer details on the test site are erased. Export the data first if you need a backup.
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 add any additional properties relevant to your product, such as file_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 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:
Using the app
CSV bulk upload. Export a CSV from your data warehouse and upload it in Chargebee Billing. Each row must include a deduplication ID, subscription ID, and usage timestamp in milliseconds.
- Go to Usages > Usage Events > Add Usage Events.
- Select the Quick file upload tab, or go to Settings > Import & Export Data > Choose a Bulk Operation, then select Usages > Create a Usage.
- Upload the file and click Proceed to review.
- Review the data, then click Import Events.
You can also add a small number of events manually: go to Usages > Usage Events > Add Usage Events, select Enter usage events, and click Import Events.
Using the API
Send events in real time or in micro-batches as they happen. You can send both raw and aggregated usage events using Ingest a usage event and Ingest usage events in batch. Usage events use the ingest host ({site}.ingest.chargebee.com), not the standard Chargebee API host.
Ingest a single usage event
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"
}
}'Ingest usage events in batch (up to 500 events per request)
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
}
}
]
}'Using Amazon S3
Upload usage event files from an S3 bucket. Chargebee Billing picks them up and processes them automatically. See Ingesting usage from Amazon S3.
Note
Backdated ingestion limits differ by method and site type. On a live site, the Usage Events API accepts events from the last 12 hours (configurable on request); CSV and S3 uploads accept events from the last 30 days. On a test site, the API window is 12 hours and file uploads accept events from the last year. See Usage-Based Billing limits.
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.
Using the app
- Go to Usages > Metered Features and click Create Metered Feature.
- Enter a name for the feature, such as File Uploads.
- Under Usage Calculation, select Sum and select the
number_of_file_uploadsevent property. - Review the usage calculation formula and preview, then click Create.
| Field | Value |
|---|---|
| Name | File Uploads |
| Feature ID | file-uploads |
| Type | Metered |
| Aggregation method | SUM. You can select Sum, Count, Min, Max, Average, or Count Distinct. |
| Event property to aggregate | number_of_file_uploads |
Using the API
The aggregation method is expressed as a SQL query over usage event properties. Chargebee Billing returns a meter whose id is also the feature ID you use in later entitlement and usage calls.
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. Do not grant included usage on this plan. In PAYG, the metered feature is linked only to the metered addon you create in the next step.
3a. Create the plan
Create a Platform plan that acts as the subscription container, and link pricing to the plan in the next step.
Using the app
- Go to Product Catalog > Plans > + Create Plan.
- Select a product family, enter the plan details, and click Create.
| Field | Value |
|---|---|
| Internal Name | Platform |
| Plan ID | platform |
Using the API
Create the plan item with Create an item. Replace {item_family_id} with your product family ID.
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.
Using the app
- Open the plan details page. In the Pricing section, click Set Price for the monthly frequency and currency you want.
- Configure the pricing as follows, then click Create.
| Field | Value |
|---|---|
| Pricing model | Flat fee |
| Price | $0 |
| Billing frequency | Monthly |
Using the API
Create the monthly price point with Create an item price. price is in the minor unit of the currency: 0 is $0.00.
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=1Do not link the File Uploads metered feature to Platform. Linking the feature to the plan would grant included usage, which this model does not use.
To keep the $0 plan fee off customer invoices, enable Hiding Zero-Value Line Items.
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
Using the app
- Go to Product Catalog > Addons > + Create Addon.
- Enter the addon details below, select This addon is metered, and click Create.
| Field | Value |
|---|---|
| Internal Name | On-demand File Uploads |
| Addon ID | on-demand-file-uploads |
| Metered | Yes |
| Metered feature | File Uploads |
Using the API
Create the metered addon with Create an item. Set metered to true.
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=trueThen link the addon to the metered feature as on-demand usage with Manage entitlements for a feature. Entitlements on metered addons are unlimited by default so every unit is billable:
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.
Using the app
- Open the addon details page. In the Pricing section, click Set Price for the monthly frequency.
- Configure the pricing as follows, then click Create.
| Field | Value |
|---|---|
| Pricing model | Per Unit. You can also use Tiered, Staircase, or Volume based on your business needs. |
| Price | $0.05 per file upload |
| Billing frequency | Monthly |
Using the API
Create the monthly price point with Create an item price. price is in the minor unit of the currency: 5 is $0.05.
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=15. 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.
Using the app
- Go to Customers and create a customer record for John Doe (Acme Inc.) if one doesn't already exist.
- From the customer, create a subscription and add the Platform monthly plan item price.
- Attach the On-demand File Uploads metered addon item price.
- Review and create the subscription.
Using the API
Create the customer with Create a customer:
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"Create the subscription with Create a subscription for items. Attach both the $0 monthly plan price and the monthly metered addon price. Chargebee Billing requires a plan on the subscription; the $0 plan is the container, and the addon is what rates usage:
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:
| Line item | Billing frequency | Invoicing |
|---|---|---|
| Platform (non-metered) | Monthly | $0. Holds the subscription. No included file uploads. Hide zero-value line items to keep this fee off the invoice. |
| On-demand File Uploads (metered) | Monthly | $0.05 per file upload invoiced at period end for every file upload recorded. If John uploaded 50,000 files in January, the February 1 invoice is $2,500. If zero files were uploaded, no charge is generated for the metered addon. |
6. Usage visibility and alerts
Use the following options to monitor usage, review billed consumption, and act before invoices surprise customers. If you do not want customers to overspend, define a spend limit and get an alert when accrued usage charges reach that amount.
Monitor usage during the current term
Using the app
Open the subscription to view cumulative file uploads under the Usage summary section.
Using the API
Retrieve usage summary to show consumed usage for a feature over a reporting window. If you omit timeframe_start and timeframe_end, Chargebee Billing defaults to the start of the current subscription term through now.
curl https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usage_summary \
-G \
-u {site_api_key}:\
--data-urlencode feature_id="file-uploads"See Retrieve usage summary for a subscription.
Retrieve usage charges to show accrued usage charges before the monthly invoice is generated. This returns the current unbilled snapshot, including total usage and the amount to invoice when a metered addon is attached.
curl https://{site}.chargebee.com/api/v2/subscriptions/{subscription_id}/usage_charges \
-u {site_api_key}:Review usage after invoicing
Using the app
Open the invoice and select View Usage PDF to review or share an itemized usage breakdown.
Using the API
Use Retrieve usage charges for a subscription to retrieve current unbilled usage charges for reconciliation or display in your application. This endpoint does not return historical, billed, or invoice-backed usage.
Configure spend alerts
Set a spend alert in Chargebee Billing and connect it to webhooks so you can notify the customer or pause usage when accrued charges reach the limit.
Using the app
- Go to Usages > Alerts and click Create Alert.
- Set a spend threshold for accrued usage charges, such as $500.
- Set the scope: apply the alert globally, filter it by plan, or override it for a subscription.
- Choose the response. Route the webhook to email, an in-app prompt, Slack, your CRM, or another workflow.
- Click Save Alert.
Using the API
Create a spend alert with Create an alert. This example fires when accrued metered-addon charges reach $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]"=500To scope an alert to one subscription instead of a plan filter, pass subscription_id and omit filter_conditions.
Related use cases
Move to a hybrid plan with included usage
PAYG customers have no upfront commitment, so they can churn easily. 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.
Example
John has been on PAYG for three months. Acme moves him to Professional at $49 per month with 100,000 file uploads included. Usage beyond 100,000 file uploads continues to bill at the metered addon rate.
Using the app
Go to the subscription, change the plan to the hybrid plan, keep the metered addon attached, and apply the change Immediately or on a Specific date.
Using the API
Use Update a subscription for items to replace the $0 platform plan price with the hybrid plan price and keep the metered addon attached.
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
Using the app
Go to the subscription, cancel the subscription, and select Immediately. Chargebee Billing invoices any accrued usage for the current period. The $0 platform plan has no prepaid amount to credit.
Using the API
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.
See also
Was this article helpful?