Set up usage-based billing

Meters specify how to aggregate meter events over a billing period. Meter events represent the raw actions that customers take in your system. Meters attach to prices and form the basis of the bill.

For the Alpaca AI example, meter events are the number of tokens a customer uses in a query. The meter is the sum of tokens over a month.

You can use the Stripe Dashboard or API to create a meter. If you want to use the API with the Stripe CLI to create a meter, learn how to get started with the Stripe CLI.

curl https://api.stripe.com/v1/billing/meters \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d display_name="Alpaca AI tokens" \
  -d event_name=alpaca_ai_tokens \
  -d "default_aggregation[formula]"=sum \
  -d "customer_mapping[event_payload_key]"=stripe_customer_id \
  -d "customer_mapping[type]"=by_id \
  -d "value_settings[event_payload_key]"=value

Use the Stripe Dashboard or API to create a pricing model that includes your products and their pricing options. Prices define the unit cost, currency, and billing cycle.

For the Alpaca AI example, you create a product with a metered price of 0.04 USD per hundred units, billed at a monthly interval. You use the meter that you created in the previous step.

curl https://api.stripe.com/v1/prices \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d currency=usd \
  -d unit_amount=4 \
  -d billing_scheme=per_unit \
  -d "transform_quantity[divide_by]"=1000 \
  -d "transform_quantity[round]"=up \
  -d "recurring[usage_type]"=metered \
  -d "recurring[interval]"=month \
  -d "recurring[meter]"={{METER_ID}} \
  -d "product_data[name]"="Alpaca AI tokens"

Next, create a customer.

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

Subscriptions allow you to charge recurring amounts by associating a customer with a specific price.

Use the Stripe Dashboard or API to create a subscription that includes your customer, product, and usage-based price.

For the Alpaca AI example, you create a subscription for the Alpaca AI product, with a metered price of 0.04 USD per unit, billed monthly to John Doe.

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

Use meter events to record customer usage for your meter. At the end of the billing period, Stripe bills the reported usage.

You can test your usage-based billing by sending a meter event through the Stripe Dashboard or API. When using the API, specify the customer ID and value for the payload.

After you send meter events, you can view usage details for your meter on the Meters page in the Dashboard.

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

Retrieve an upcoming invoice to see a preview of a customer’s invoice that includes details such as the meter price and usage quantity.

curl -G https://api.stripe.com/v1/invoices/upcoming \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}}