Usage-Based Subscriptions

Company A (Volume pricing model)

• Sells software access per seat via license keys.
• Prices change with the number of seats (volume pricing model):
  • up to 4 seats at $9/month/seat
  • up to 10 seats at $8/month/seat
  • up to 20 seats at $6/month/seat.

Company B (Package pricing model)

• Operates an API platform
• Charges €9 per package of 1,000 API call credits (package pricing model).

Company C (Graduated pricing model)

Runs a database platform, charging by the number of queries:

• $0.03 per query for the first 1,000 queries
• $0.02 per query for the next 1,000 queries
• $0.01 for all subsequent queries (graduated pricing model)

These companies periodically send usage data to Lemon Squeezy, so the invoices reflects the number of actual units used.

Enable usage-based billing on products

Create a product and toggle on the “Usage is metered?” option in the product settings.

Choose how usage will be calculated, e.g., “Maximum usage during period” or “Sum of usage during period.”

Set up webhooks

Set up webhooks to automatically receive data when subscriptions are created or updated. Webhooks can be created in your dashboard or via API. For a full implementation, refer to our Developer Guide.

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.

Send customers to checkout

Customers purchase your products via checkout URLs like they would normally do. With usage-based billing enabled, no charge is made at checkout, but payment details are captured for future renewals.

Report usage to Lemon Squeezy

Send usage data to Lemon Squeezy as frequently as needed.

• For example, if you’re selling seats, you can report usage to Lemon Squeezy when a new team member is added to an account.
• Or, 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"
          }
        }
      }
    }
  }'

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 reporting to Lemon Squeezy that the user has used an additional 23 units of units.