Usage-Based Billing

Charging customers based on their usage is a common practice in software.

With Lemon Squeezy, you can implement this by leveraging our various pricing models and opting for quantity, or usage-based billing.

Pricing models

There are four different ways to charge in Lemon Squeezy.

Ways to charge for usage

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.

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 100 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:

https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]?quantity=100

If you create checkouts using the API, you can similarly determine a quantity in checkout_data.variant_quantities.

POST https://api.lemonsqueezy.com/v1/checkouts

{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "variant_quantities": [
          {
            "variant_id": 1,
            "quantity": 10
          }
        ]
      }
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      },
      "variant": {
        "data": {
          "type": "variants",
          "id": "1"
        }
      }
    }
  }
}

Updating quantity

When using quantity-based billing, you can change the quantity of a subscription by updating the Subscription item’s quantity value.

PATCH https://api.lemonsqueezy.com/v1/subscription-items/1

{
  "data": {
    "type": "subscription-items",
    "id": "1",
    "attributes": {
      "quantity": 5
    }
  }
}

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.

GET https://api.lemonsqueezy.com/v1/subscription-items/1

to get a response like this:

{
  "type": "subscription-items",
  "id": "1",
  "attributes": {
    "subscription_id": 1,
    "price_id": 1,
    "quantity": 1,
    "is_usage_based": false,
    "created_at": "2023-07-18T12:16:24.000000Z",
    "updated_at": "2023-07-18T12:16:24.000000Z"
  },
  ...
}

For more information please refer to the API reference

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”).

POST https://api.lemonsqueezy.com/v1/usage-records

{
  "data": {
    "type": "usage-records",
    "attributes": {
      "quantity": 1,
      "action": "increment"
    },
    "relationships": {
      "subscription-item": {
        "data": {
          "type": "subscription-items",
          "id": "1"
        }
      }
    }
  }
}

Go to the API reference.

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.

GET https://api.lemonsqueezy.com/v1/subscription-items/1/current-usage

{
  "jsonapi": {
    "version": "1.0"
  },
  "meta": {
    "period_start": "2023-08-10T13:08:16+00:00",
    "period_end": "2023-09-10T13:03:16+00:00",
    "quantity": 5,
    "interval_unit": "month",
    "interval_quantity": 1
  }
}

API reference.

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.