Set up usage-based billing with rate cardsPrivate preview

Charge customers based on usage of your products or services with rate cards.

You can subscribe customers to many different rates for usage-based services through one rate card. You can add new rates to the rate card and immediately apply those new rates to customers. Rate cards are versioned, so you can adjust rates for new customers while keeping existing customers at an older rate.

Private preview

Rate cards are currently in private preview and could change in functionality and integration path before they’re generally available to all Stripe users. Contact here to request access.

Before you begin

Rate cards use /v2 API endpoints, such as Rate card subscriptions. Learn more about the /v2 and /v1 namespaces.

Use sandboxes to test your rate card integration. You can’t use test mode with /v2 APIs like Rate Cards.

Create a rate card

Use the Stripe Dashboard or API to create a rate card that contains multiple rates, with each rate specifying a billable item, a meter, and a pricing model.

For each rate card, you can configure:

Service interval: Monthly, annual, weekly, or custom.
Currency
Include tax in prices: Specify whether to include tax in your price (inclusive) or to add it to the invoice subtotal (exclusive). Learn more about inclusive and exclusive taxes for billing.

You can’t change the service interval, currency, or tax calculation parameters after you create the rate card.

After you set the service interval, currency, and tax parameters, you can define multiple rates within the rate card. Each rate specifies a billable item (what you’re selling), the meter that tracks usage of that item, and the pricing model applied to the usage:

Price type: Fixed rate, volume, or graduated.
Sell as: Charge by individual units or by a packaged group of units. If you use packages, you specify the number of units per package and how to round (up or down) for partial packages.
Advanced settings: You can optionally specify the product tax code. You can also add a unit label, a lookup key, and metadata on the rate and the billable item.

You can add new rates to a rate card at any time. If you modify or delete existing rates, a new version of the rate card is created.

When you create a rate card, provide a display name, currency, service interval, and tax behavior.

After you submit the rate card request, Stripe returns the active rate card object. You can’t subscribe new customers to an inactive rate card.

rate card response example
{
  "id": "rcd_test_61RVeJCo447E9aFii16RMt7iESSQdRfzhYKc3x1HkXDM",
  "object": "billing.rate_card",
  "active": true,
  "created": "2024-11-17T21:49:50.000Z",
  "currency": "usd",
  "display_name": "Alpaca AI rate card",
  "metadata": {},
  "service_interval": "month",
  "service_interval_count": 1,
  "latest_version": "rcdv_123",
  "live_version": "rcdv_123", // defaults to first version created
  "tax_behavior": "exclusive"
}

Create a metered item to define the granular item you’re selling, like Alpaca AI tokens.

Set the rate for the metered item by creating a rate card rate.

You can also create a rate card rate that uses tiered pricing:

Before you create a subscription, you need to create a Customer object and provide billing information. You can do this in the Dashboard, with the API, or by using Stripe Checkout.

Manually create a customer in the Dashboard and add their billing information. Alternatively, you can create a customer when you create the rate card subscription.

Go to the Rate cards page and click the rate card you want to subscribe your customer to.
In the rate card details page, click the overflow menu () next to Edit rate card.
In the rate card subscription editor:
- Find or add a customer.
- Define the Billing cadence, which is how often to and when to send an invoice to the customer.
- Click Create subscription.

Record customer usage

After you subscribe a customer to a rate card, you can record their usage of your service, by sending meter events to a meter.

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

To test usage-based billing, send meter events through the Stripe Dashboard or API. When using the API, specify the customer ID and usage value in the payload.

Create a preview invoice

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

Monitor servicing events

Rate card subscriptions emit event notifications whenever the state of servicing changes. Learn more about how the service interval works.

Listen for these events and use them to construct your business logic:



`v2.billing.rate_card_subscription.servicing_activated`	Sent when a customer activates a subscription for the first time.
`v2.billing.rate_card_subscription.servicing_paused`	Sent when a customer pauses a subscription.
`v2.billing.rate_card_subscription.servicing_canceled`	Sent when a customer cancels a subscription.

To handle these v2 Events, configure an Event Destination and point it at your webhook endpoint. You can either:

Create the Event Destination from Workbench.
Create the Event Destination through the Stripe API.

After you’ve created a destination, you can set up your webhook endpoint to handle these events:

server.rb
require 'stripe'

post '/v2_webhook_endpoint' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    status 400
    return
  end

  client = Stripe::StripeClient("sk_test_BQokikJOvBiI2HlWgH4olfQ2"
)

  case event.type
  when 'v2.billing.rate_card_subscription.servicing_activated'
    # The customer clicked Pay on Stripe Checkout, which activates the service.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.rate_card_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_active(user, subscription)
  when 'v2.billing.rate_card_subscription.servicing_paused'
    # The customer paused the subscription.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.rate_card_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_paused(user, subscription)
  when 'v2.billing.rate_card_subscription.servicing_canceled'
    # The customer canceled the subscription.
    subscription_id = event.related_object.id
    subscription = client.v2.billing.rate_card_subscriptions
      .retrieve(subscription_id)

    # Look up your user in the database using the metadata passed into
    # Checkout Session create
    user_id = subscription.metadata["my_user_id"]
    user = User.find_by_id(user_id)

    # Fill in your logic here:
    mark_subscription_canceled(user, subscription)
  end

  status 200
end

Set up usage-based billing with rate cardsPrivate preview

Charge customers based on usage of your products or services with rate cards.

Private preview

Before you begin

Create a rate card

Record customer usage

Create a preview invoice

Monitor servicing events

OptionalTest the integration

OptionalCollect taxes

OptionalRetrieve usage for a custom time period

Set up usage-based billing with rate cardsPrivate preview

Charge customers based on usage of your products or services with rate cards.

Private preview

Before you begin

Create a rate card

Subscribe your customer to a rate card

Record customer usage

Create a preview invoice

Monitor servicing events

OptionalTest the integration

OptionalCollect taxes

OptionalRetrieve usage for a custom time period