Usage-based billing
It is common in software to charge customers by usage of your product.
This is possible in Lemon Squeezy when selling subscriptions using one of our various pricing models and using quantity- or usage-based billing.
During subscriptions you can report real-time usage back to Lemon Squeezy so that your customers are charged the correct price based on how much they are using your product.
Pricing models
There are four different ways to charge in Lemon Squeezy.
Flat-rate pricing
Flat-rate pricing is the simplest way to charge and can be used on both single payment and subscription products.
- Standard pricing - Charge a flat rate for a single unit
- Package pricing - Charge a flat rate for multiple units
Examples:
- You sell access to your software per seat at $9/month per seat (Standard pricing).
- You sell units for your application at $10 for 100 units (Package pricing).
You can change the price of an order or an initial subscription charge by specifying a quantity value at checkout (read on to find out how).
Updating an active subscription's quantity is similar to changing its plan; customers can be charged a prorated amount (based on your API request) and changed to a higher or lower renewal price.
Tiered pricing
Tiered pricing models let you charge per unit, giving you more granular and precise pricing options.
- Volume pricing - Charge a flat rate per unit depending on total usage
- Graduated pricing - Charge variable unit prices depending on total usage
Examples:
- You sell access to your software per seat; up to a maximum of 3 costs $5/month each and after that all seats cost $4/month (Volume pricing).
- You sell access to your software per seat in differently-priced tiers; the first 3 seats cost $5/month each, the next 5 seats cost $4/month each and every additional seat costs $3/month (Graduated pricing).
For tiered pricing you can either use quantity-based billing to determine how much customers are charged (like with standard and package pricing) or enable usage-based billing for easier usage reporting (see below).
Graduated and volume pricing also support charging a flat fee for each pricing level, which is great if you want to charge a set-up or base fee alongside product usage.
Ways to charge for usage
Quantity-based billing
The simplest way to charge for usage is by using a quantity value for each subscription.
Customers are charged up-front based on an optional quantity set at checkout and then can be charged during a subscription for different usage as you change the quantity value. This simply changes the next renewal amount to a specific multiple of your unit price and the end effect is similar to changing a subscription's plan.
You can use this billing method on all four pricing models.
Usage-based billing
For more flexibility for reporting usage in your platform, you can enable usage-based billing on specific products and variants.
With usage-based billing, customers are charged based on usage during the previous billing period rather than up-front.
The advantages of using usage-based billing are:
- A higher degree of flexibility when reporting real-life product usage. Instead of simply updating a subscription's
quantityvalue you can send multiple API requests to record usage over time, which Lemon Squeezy then uses to charge your customers. - Being able to charge in arrears accurately based on exact usage, rather than up-front using a quantity value (which is more like changing between plans than charging by usage).
Note that when you use usage-based billing, the initial charge at checkout will always be 0. Any quantity value set at checkout will be ignored.
Usage-based billing can be enabled on all four pricing models.
Reporting usage for quantity-based billing
Setting a quantity at checkout
When customers buy your product, you can set a unit quantity value at checkout allowing you to start subscriptions with a pre-defined amount of units.
If you do not specify a quantity at checkout, it will always default to 1.
The total charged at checkout will be based on your pricing model, unit prices and the quantity specified. For example, if you sell API credits using volume pricing at $0.10 per credit, setting a quantity of 1000 at checkout will charge the customer $10.
We recommend you test changing the quantity value at checkout to see how prices will be shown to your customers and to make sure your pricing has been set up correctly on your products.
To specify a quantity at checkout you can add the query parameter quantity to a product's share URL:
If you create checkouts using the API, you can similarly determine a quantity in checkout_data.variant_quantities.
Updating quantity
When using quantity-based billing, you can change the quantity of a subscription by updating the Subscription item's quantity value.
(You can get the subscription item ID from a Subscription object's first_subscription_item.id value.)
Doing this will change how any units to charge for on the next renewal date. For example, if you sell a £19/month subscription, changing the quantity value to 4 will charge £76 at the next rewenal.
A prorated amount will be added to the customer's next subscription invoice if quantity increases, to reflect the increased usage for the remaining part of the current billing period.
Querying quantity
If you ever need to query the current quantity of a subscription, send a GET request to the Subscription item endpoint.
Reporting usage for usage-based billing
For more flexibility and control in reporting usage, you can activate Usage-based billing on your products and report customer usage to Lemon Squeezy using Usage records endpoints.
Reporting usage
When reporting usage there are two options you use in tandem to tell Lemon Squeezy how many units have been used by your customers and how to charge against that usage.
The first option is the aggregation setting you choose in the product/variant form when enabling usage-based billing. These options are:
- Sum of usage during period
- Most recent usage during a period
- Most recent usage
- Maximum usage during period
The second option is the type of usage records you make to Lemon Squeezy, determined with the action value in API calls.
If you have chosen the "Sum of usage during period" aggregation setting, you should use "action": "increment", which will add the provided quantity value to any existing quantity for the current billing period.
If you have chosen the "Most recent usage during a period" or "Most recent usage" aggreagation settings, you should use "action": "set", which will replace any existing usage with the provided quantity value.
In this example, we are adding 1 more unit to the existing usage (aggregation for this product is "Sum of usage during period").
Querying usage
You can always view a subscription's real-time billable usage from your dashboard.
To retrieve the current usage of a subscription with the API, make a GET request to the subscription item's current usage endpoint.
The quantity value updates every time you send a usage record request. It will always reflect the unit usage that will be used in the next invoice (calculated using your usage aggregation setting), so you can easily show your customers how many units they have used.