Usage-based Billing

Usage-based billing (sometimes known as “metered billing”) is a system that lets you easily report customer usage back to Lemon Squeezy when selling subscriptions on any of our four pricing models.

---

When usage-based billing is activated in a product or variant’s settings you will be able to report to Lemon Squeezy whenever there is a change in your customer’s usage. Lemon Squeezy will then bill your customers on the next renewal date based on this usage.

You can turn it on using the “Usage is metered?” option:

Usage aggregation setting

When setting up usage-based billing on a product, you can specify how you want to bill against the usage you have reported over the API.

This setting will be used when Lemon Squeezy makes future subscription payments and also determines which type of usage records you can report back to Lemon Squeezy.

• Sum of usage during period - Use this if you want to charge using a total of all usage records reported during the current billing period.
• Most recent usage during a period - Use this if you want to charge based on the latest reported usage in the current billing period. If there is no reported usage in the current billing period, usage will be 0.
• Most recent usage - Use this if you want to charge based on the latest reported usage (this could have been reported in either the current or a previous billing period).
• Maximum usage during period - Use this if you want to charge based on the highest reported usage during the current billing period. If there is no reported usage in the current billing period, usage will be 0.

Usage-based billing at checkout

When a customer purchases a product with usage-based billing enabled, they will not be charged at checkout unless the setup fee option is enabled for the product.

The default “Pay” button will be replaced with a “Create subscription” button.

If you set a quantity value at checkout on a product that has usage-based billing enabled, it will be ignored. The initial charge will always be 0.

All charges for usage-based billing are made retrospectively based on reported usage during the previous billing period.

Setup fees

When a customer purchases a product with setup fees, they will be immediately charged with that fee.

For example, when you sell a usage-based product for $10 per unit with a setup fee of $5, a customer will be charged $5 at checkout, and then the regular fee at the end of each billing cycle, depending on usage.

How to report usage

You can inform Lemon Squeezy of each customer’s usage using our Usage records API endpoints.

Whenever you want to report new usage, you can send a new request to the API. Lemon Squeezy will keep a record of all of your usage reports and then charge customers based on your aggregation setting.

Read the API docs for Usage records or view a full example in our Developer Guide.