Set up usage-based billing
Understand the major pieces of a usage-based billing integration.
Note
We updated our usage-based billing process. For information on our previous guidance, refer to our legacy usage-based billing documentation.
This guide explains the core concepts of a usage-based billing model through the perspective of a fictional Gen AI company called Alpaca AI. Alpaca AI charges their users 0.04 USD per 1,000 tokens of consumption, billing at the end of the month in arrears.
- Meter events: You send customer-specific information, represented by meter events, to Stripe. These events represent the raw action a customer took in your system, forming the basis of their bill. In our example, this refers to the number of tokens a customer used in a query.
- Meter: Meters, as configuration objects for meter events, provide guidelines on how you want the meter events aggregated over the billing period. In this case, this refers to the sum of tokens over a month. Meters attach to prices, mapping the customer usage to customer subscriptions.
- Meter event summary: The event summary for a customer and meter returns aggregated usage for a period (the meter defines the aggregation formula). In our example, the meter event summary returns the sum() of tokens for a specific customer, meter, and time window. Meter events don’t become available on the read path and are asynchronously aggregated into Meter event summary results.
- Prices: Prices define the unit cost, currency, and billing cycle. In our example, you define a package price of 0.04 USD for 1000 tokens, billed at a monthly interval. Learn more about Prices.
- Subscription: Subscriptions allow you to charge recurring charges by associating a user with a specific price. Learn more about Subscriptions.
This diagram demonstrates the core concepts:
What you will build
This guide shows you how to:
- Model your business by building a Billing Meter and product catalog
- Add payment collection session to your site
- Monitor subscription events
Set up Stripe
Install the Stripe client of your choice:
Next, install the Stripe CLI. The CLI provides webhook testing, which you can run to make API calls to Stripe. This guide demonstrates how to use the CLI to set up a pricing model in a later section.
For additional install options, see Get started with the Stripe CLI.
Create a meter
Create the meter in the Dashboard or with the API. You can create the meter from the products and prices page in the next step.
Learn more about configuring meters.
Create a pricing model
Create your products and their pricing options in the Dashboard or with the Stripe API.
Create a customer
You must create a customer for each subscription. In your application frontend, collect any necessary information from your users and pass it to the backend.
On the server, create the Stripe customer object.
Subscribe customer to the usage-based price
On the backend, subscribe the customer to the usage-based price.
This returns a subscription object with a SetupIntent you need to collect payment information.
Collect payment information
See how to collect payment details with the client secret found in the response from creating the subscription.
Report usage
You can start recording usage against the meter for the customer using Meter Events. Specify the customer reference and the value in the payload. Stripe bills the reported usage to the customer at the end of the billing period.
Learn more about recording usage.