Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in

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:

Command Line
# Available as a gem
sudo gem install stripe
Gemfile
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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.

Command Line
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

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.

  1. Navigate to the Meters tab.
  2. Click + Create meter.
  3. Enter the name of the meter (in this case, “Alpaca AI tokens”) for display and organization purposes.
  4. Enter the event name (in this case, alpaca_ai_tokens). You use this name in Meter Events to report usage to Stripe.
  5. Select sum as the aggregation formula.

Learn more about configuring meters.

Create a pricing model

Create your products and their pricing options in the Dashboard or with the Stripe API.

To create a metered usage pricing model in the Dashboard:

  1. Navigate to the Products tab.
  2. Click + Add product.
  3. Enter the name of the product (in this case, “Alpaca AI”).
  4. (Optional) Add a description. The description appears at checkout in the customer portal and in quotes.

Next, add a recurring price to the Alpaca AI product:

  1. Select Usage-based and Per package pricing for the pricing model.
  2. Set the amount to 0.04 USD per 1000 units, and the billing period to monthly.
  3. Add the meter alpaca_ai_tokens. Optionally, create the meter if you haven’t already.

Use the id of this price when you create subscriptions.

Learn more about different pricing models.

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.

Command Line
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d name="John Doe"

Subscribe customer to the usage-based price

On the backend, subscribe the customer to the usage-based price.

Command Line
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}} \
  -d "items[0][price]"={{PRICE_ID}} \
  -d "expand[0]"=pending_setup_intent

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.

Command Line
curl https://api.stripe.com/v1/billing/meter_events \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d event_name=alpaca_ai_tokens \
  -d "payload[value]"=25 \
  -d "payload[stripe_customer_id]"={{CUSTOMER_ID}}

Learn more about recording usage.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
On this page
What you will build
Set up Stripe
Create a meter
Create a pricing model
Create a customer
Subscribe customer to the usage-based price
Collect payment information
Report usage
Related Guides
Usage-based pricing models
Products Used
Billing