How to set up usage-based billing for SaaS subscriptions: Lemon Squeezy

Dan Rowden · September 4, 2023

We recently released a whole new way to charge subscription customers on Lemon Squeezy: usage-based billing.

In this tutorial I'll take you through the main concepts behind usage-based billing, explain a few real-life examples of usage-based pricing models and then a walkthrough of how to start charging customers based on usage with Lemon Squeezy.

Usage-based billing core concepts

The idea behind usage-based billing is to charge customers based on what they used rather than charging them based on what they plan to use.

With a typical subscription, the customer will be billed up-front based on a given unit price and quantity. With a usage-based subscription, the quantity is unknown until the end of the billing cycle, so the customer will be billed in arrears.

In Lemon Squeezy, usage-based billing is an optional setting you can apply to individual products and variants.

When the "Usage is metered?" toggle is active, a few things happen:

Customers are not charged anything at checkout when they start a subscription
Your application should send Lemon Squeezy up-to-date usage information during the subscription
Customers are charged in arrears for the usage reported to Lemon Squeezy by your application

You also have an option to choose how usage records are used to bill customers, like "Sum of usage during period" or "Most recent usage". These options give you fine-grained control about how the recorded usage is applied to payments.

Alongside flat-fee pricing models that charge a flat fee per unit, we also offer two tiered pricing models, volume and graduated, with which you can create detailed and specific pricing for your products. With volume pricing, you can charge a set unit fee, which changes based on total units used. Graduated pricing lets you charge variable unit costs in different tiers as usage increases.

Examples of usage-based billing

There are many ways to charge for subscriptions based on unit usage. In Lemon Squeezy you can sell anything based on "units", like seats, minutes, views, transactions, storage space, etc. Anything linked to a "unit" can be charged with usage-based billing.

Here are some real-life examples:

Company A is a software company selling access to their applications by seat using license keys. They sell up to four seats for $9/month/seat, up to 10 seats for $8/month/seat and up to 20 seats for $6/month/seat (volume pricing model).
Company B runs an API platform, selling packages of API calls. They charge €9 for each package of 1,000 credits purchased (package pricing model).
Company C is a database platform, charging by the amount of queries made. They charge $0.03 per query for the first 1,000 queries, $0.02 per query for the next 1,000 queries and then $0.01 for all subsequent queries (graduated pricing model).

For each of these examples, when usage-based billing is enabled, the company can periodically send Lemon Squeezy usage data. The next invoice created will be tied directly to the number of units their customers have used.

How to add usage-based billing to your app

1. Enable usage-based billing on products

The first step to adding usage-based billing to your application with Lemon Squeezy is to create the products and toggle on the "Usage is metered?" option in the product settings.

Once enabled, you need to choose how usage will be calculated. For example, "Maximum usage during period" will use the highest usage record for the next invoice, whereas "Sum of usage during period" will total all usage records from the current billing period and charge based on that.

2. Set up webhooks

In order to properly use the usage-based billing system, we recommend you set up webhooks so that your application can get sent data automatically when subscriptions are created or updated in your Lemon Squeezy store.

Webhooks are easy to create either in your dashboard or with our API. Once created, Lemon Squeezy will start sending data to your application for every event you chose to receive alerts for.

Please read the Developer Guide to view a full webhook implementation.

You will also need certain data stored locally in your application, like subscription item IDs needed to report usage. Read our suggested list of data to store locally.

3. Send customers to checkout

Customers will be able to buy your products from your checkout URLs like normal. This can be done by linking to the hosted checkout or using our overlay checkout, which creates a more seamless experience within your application.

With usage-based billing enabled, customers won't be charged anything at checkout but their payment details will be captured for future renewals.

4. Report usage to Lemon Squeezy

When you have active subscriptions, you can then start sending usage data to Lemon Squeezy.

You can report usage as frequently as you like, whenever it makes sense in your application.

For example, if you're selling seats, you can report usage to Lemon Squeezy when a new team member is added to an account. If you're selling API credits, you can report to Lemon Squeezy immediately after each credit is used, or daily with an update of customers' total usage for the billing period.

To make usage reports use our usage record endpoint:

curl -X "POST" "https://api.lemonsqueezy.com/v1/usage-records" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "usage-records", "attributes": { "quantity": 23, "action": "increment" }, "relationships": { "subscription-item": { "data": { "type": "subscription-items", "id": "1" } } } } }'

API reference.

In API calls you need to report usage either as an incremental change or to replace any previous usage total. This is based on the usage aggregation you chose when enabling usage-based billing on your product (Step 1).

Using "action": "increment" will add the provided quantity value to any existing quantity for the current billing period. Use this with "Sum of usage during period".
Using "action": "set" will replace any existing usage with the provided quantity value. Use this with "Most recent usage during a period" and "Most recent usage".

In the example above, we are informing Lemon Squeezy that the customer has used a further 23 units.

5. Query usage during subscriptions

After you have started reporting usage, you may want to retrieve a customer's usage for their upcoming invoice.

You can see current usage for every subscription in the dashboard.

You can also get this information with the API by making a GET request to a subscription item's current usage endpoint.

curl -X "GET" "https://api.lemonsqueezy.com/v1/subscription-items/1/current-usage" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "jsonapi": { "version": "1.0" }, "meta": { "period_start": "2023-09-27T13:08:16+00:00", "period_end": "2023-10-27T13:03:16+00:00", "quantity": 1240, "interval_unit": "month", "interval_quantity": 1 } }

The quantity returned here reflects a customer's unit usage that will be used in the next invoice, which is calculated using your usage aggregation setting from step 1. You can confidently use this figure to show customers their current billable usage amount in your application.