Getting Started

Building Blocks

Subscription Features




Billing Features


Payment Methods

Direct Debit Payments

Configuring Gateways

Fraud Management

Hosted Pages


Reports and Analytics

Attach Additional Data


Open Source Resources

Other Features

API Integration

Third Party Integrations

Metered Billing 

Metered billing or usage-based billing of subscriptions typically works with a plan that includes a base fee and a usage fee. Some businesses will also have overage charges when users exceed the base limit included in their subscription. So a customer gets charged a flat fee for their plan plus for usage or if they exceed the allocated amount.

With Chargebee's metered billing solution, you can flawlessly charge your customers based on their usage of products and services - you just need to tell us how much to charge them and how much they've used.

You can use metered billing to include ad hoc charges for usage of services by calculating and specifying the amount to be charged on the invoice. You can also create non-recurring, quantity based add-ons to track usage and charge customers for it. You need to just specify the quantity used and Chargebee will calculate the total usage charge and add it to the invoice.

Chargebee notifies you when an invoice is generated, and lets you seamlessly add the line items to the open invoice and post the charge.

To enable metered billing, login to the web interface, go to SettingsSite Info, enable Notify and wait to close Invoices and click Update Site Info. Once this is done, you are all set.

How does it work? 

When this option has been enabled, Chargebee will create a pending invoice and a pending_invoice_created event will be fired (Event types ) during one of these 2 conditions:

  1. Subscription Renewal

  2. Plan changes (upgrade/downgrade or quantity changes) in the subscription

You will receive generated invoices in your webhook handler, and after receiving the invoice, you can use the ID of the invoice resource to add the usage charges to the invoice received.


During the generation of a "Pending" Invoice, the invoice number will not be taken from the main sequence. A temporary invoice number in the ‘draft_inv_' format will be assigned to it.

APIs used are:

Add Charge to Invoice

The Add Charge to Invoice  API call is used to add the line items to the invoice after you have calculated how much the customer needs to be charged.

Add Addon Charge to Invoice

For subscription models that include add-ons as metered components, you can create and use non-recurring quantity based addons, and charge customers based on their usage. You just need to specify the total add-on quantity used. Use the Add Addon Charge to Invoice  API call to do this.


You can override the price of the addon(s) before appending it to the invoice by specifying a new price using the Add Addon Charge to Invoice   API call.

Close Invoice

Once all the usage based charges have been added to the invoice, you can initiate the API call Collect Invoice  to go ahead and post the charges. Chargebee will then close the invoice and simultaneously attempt to make a charge on the card that is on file.


While closing the pending invoice, the invoice number will be assigned based on the current invoice number sequence. The invoice end date will also be updated with the date of closure.

When is the usage fee collected? 

Chargebee bills the customer for the base fee during sign up and the usage fee will be charged during the next month's renewal. Basically, recurring costs are charged upfront and usage based fees are added to the next month's charges. Invoices are not notified during account activation, but only when the subscription renews or when a plan is upgraded/downgraded or the quantity changes.

Let us consider an online video streaming service:


Signup Date and Current Term: 1st May 2012 - 1st June 2012

Plan Fee: $100

Usage Fee: .10c / hr

Hours Used: 300

Usage Charges: $30

Total Charges on renewal: $130

Customer will be charged the $100 plan fee during sign up, and $130 on June 1st ($30 along with $100 renewal fee).


All notified invoices will remain open until you add the charge and/or close the invoice.

What happens when a customer upgrades/downgrades? 

If a customer is switching between plans during mid term, prorated charges will be applied immediately and the invoice to add the metered components will be generated as well.


Plan A: $30/Month

Subscribed Date: 1 Jan 2014

Plan B: $60/Month

Upgraded Date: 20 Jan 2014

When the upgrade happens, the customer will be immediately moved to plan B and the invoice to add the metered components will be generated immediately.

When downgrading from a higher plan to a lower plan, the prorated difference that needs to be returned to the customer will also be added as credits to their subscription and the credits will be applied along with the same invoice.