Legacy
Usage records Legacy
Charge customers based on how much they use your product or service.
This page documents legacy usage-based billing. We’ve updated the way usage records billing works—use Metronome instead for new integrations.
Upgrade your SDK
If you’re on a Stripe SDK version that deprecated UsageRecords and need to upgrade for unrelated features, you can continue using the legacy UsageRecords and metered Price APIs by pinning to a pre-Basil API version using RawRequest. This lets you upgrade your SDK without disrupting your metered billing integration. See Upgrade your SDK without migrating from usage records.
Get started
Usage records pricing model
Learn how to model usage records pricing on Stripe.
Record usage
Record the usage of your users and report it to Stripe.
How usage records billing works
Understand the major pieces of a usage records integration.
Migrate to basic usage-based billing
Migrate from usage records to basic usage-based billing if you have a pay-as-you-go pricing model.
Upgrade your SDK without migrating
Use RawRequest with a pinned pre-Basil API version if you upgraded your Stripe SDK but still rely on legacy UsageRecords.
Usage records lifecycle
Here’s what the lifecycle of a usage records integration looks like. This diagram illustrates what happens after you’ve implemented a customer experience.
Sample integration
This example walks through the implementation of a fictional font service called Typographic.
Create a product and pricing
Model your business on stripe with products and prices.
Create your products and their pricing options with the Stripe API or Dashboard. Typographic has three products, each with two tiers:
- Standard
- Tier one: 10 USD per month for 10,000 requests
- Tier two: An additional 0.10 USD for each request after 10,000
- Growth
- Tier one: 25 USD per month for 10,000 requests
- Tier two: An additional 0.10 USD for each request after 10,000
- Enterprise
- Tier one: 75 USD per month for 10,000 requests
- Tier two: An additional 0.0075 USD for each request after 10,000
To achieve this kind of pricing, you charge a flat rate and an additional amount based on how much customers use. With graduated tiers, customers initially pay the flat rate for the first 10,000 requests. If they make more requests than that, they reach tier two and start paying for each additional request. You could also charge solely based on usage without the flat rate.
During each billing period, you create usage records for each customer and then Stripe adds them up to determine how much to bill for. This process is explained in a subsequent step but understanding the default behavior might impact how you create prices.
To create a metered usage pricing model on Stripe through the Dashboard:
First, create the Standard product. To learn about all the options for creating a product, see the prices guide.
- Go to the Products tab .
- Click + Add product .
- Enter the Name of the product: Standard , in this case.
- (Optional) Add a Description . The description appears at checkout, on the customer portal , and in quotes .
Next, create the monthly price for the Standard product. Select Graduated pricing for the Pricing model, then select Recurring.
Create two graduated pricing tiers:
| First unit | Last unit | Per unit | Flat rate | |
|---|---|---|---|---|
| For the first | 0 | 10,000 | 0.00 USD | 10.00 USD |
| For the next | 10,001 | ∞ | 0.10 USD | 0.00 USD |
Then, select Monthly for the Billing period and check Usage is metered.
Repeat the steps for the Growth and Enterprise products, filling in the appropriate values as necessary.
Read the docs to learn more about different pricing models.
Sign up customers
To let your customers sign up for your services, you need to present a payment form on your website. Use Stripe Checkout to embed the form on your site or redirect customers to a Stripe-hosted form. When a customer selects a recurring product and enters their billing information in the Payment Link, Stripe creates two records:
- Customer
- Subscription These records are both stored within Stripe.
Stripe offers other options for setting up your payment form:
- Pricing tables : Create a pricing table from the Stripe Dashboard and embed it on your site. When a customer selects a plan, they’re taken to your payment page. Pricing tables don’t support sub-cent pricing.
- Web Elements : Build custom checkout flows to integrate with your site.
Create a usage record
Throughout each billing period, you need to report usage to Stripe so that customers are billed the correct amounts. You can maintain your own system for recording customer usage and provide usage information for subscriptions to Stripe.
Learn how to record and report usage.
Test your integration
Test your integration to make sure it behaves as you expect. Learn more about testing subscriptions integrations.
You can use test clocks to test different scenarios, including mock usage records. When you make a usage reporting call, you need to sync the timestamp of the test clock with the usage records. Make a note of the test clock timestamp so that your usage records fall within the same time window. Learn more about test clocks.