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

Set up usage-based billing with rate cardsPrivate preview

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

Copy page

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 /v2 API endpoints, such as Rate card subscriptions. Learn more about the /v2 and /v1 namespaces.

You can only use sandboxes with /v2 APIs.

Create a rate card

Use the Stripe Dashboard or API to create a rate card that can include multiple rates and pricing option.

For each rate card, you can configure:

  • Service interval: Monthly, annual, weekly, or custom.
  • Currency
  • Include tax in prices

For each item in a rate card, you can configure:

  • Meter: Which meter to use to record 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, metadata, and rate settings metadata.

You need to associate each rate in a rate card with a meter.

  1. Go to the Rate cards page. Click + Create rate card.
  2. In the rate card editor, set up the rate card:
    • Rate card name: Add a name for your rate card. For example, Alpaca AI.
    • Service interval: Select the time period for when a customer’s usage is aggregated and priced. Learn more about the service interval.
    • Currency: Select the Currency.
    • Tax behavior: Select whether to Include tax in prices. The default is to not include tax in prices. Learn more about tax behavior and rate cards.
    • Click Continue.
  3. In the next screen of the rate card editor, add a metered item:
    • Metered item: Enter a name for your item. For example, Alpaca AI tokens.
    • Meter: Select an existing Meter or create a new one by clicking +.
    • Price configuration: Select the Price type: Fixed rate, Volume, or Graduated. For example, Alpaca AI uses Fixed rate.
      • Select whether Sell as Individual units or a Packaged group of units. For example, an AI company might sell their tokens as packages of 100 units, at 0.04 USD per package.
      • For packages, Enter the Units per package.
      • Select whether to round up or down for Partial packages. If you round up, a user that uses 110 units is charged 0.08 USD.
      • Enter the Price per package.
    • (Optional) You can optionally configure Advanced settings for your item, like specifying a Product tax code (learn more about tax codes), Unit label, Lookup key, and Metadata. You can also add metadata to the rate.
    • Click Save.
  4. Click to add another rate.
  5. Click Create rate card.

Subscribe your customer to a rate card

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.

  1. Go to the Rate cards page and click the rate card you want to subscribe your customer to.
  2. In the rate card details page, click the overflow menu () next to Edit rate card.
  3. 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.

  1. Go to the Rate card subscriptions tab.
  2. Click the subscription you want to record usage for.
  3. Click the overflow menu () in the row of the item you want to record usage for, then click View meter details.
  4. In the meter details page, click + Add usage then select Manually input usage.
  5. In the Add usage dialog:
    • Select a customer.
    • Enter a Value for the usage.
    • Select a date for the Timestamp.
  6. Click Submit.

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.

  1. Go to the Rate card subscriptions tab.

  2. Click the subscription you want to preview an invoice for.

  3. Scroll down to the Upcoming invoice section. The preview invoice shows the subscription amount to bill the customer on the specified date.

  4. Click View full invoice to see complete details for the upcoming invoice, including:

    • Customer
    • Billing method
    • Creation date
    • Connected subscription
    • Subscription details (usage quantity and meter price)
    • Amount due

    Because Stripe processes meter events asynchronously, upcoming invoices might not immediately reflect recently received meter events.

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_activatedSent when a customer activates a subscription for the first time.
v2.billing.rate_card_subscription.servicing_pausedSent when a customer pauses a subscription.
v2.billing.rate_card_subscription.servicing_canceledSent 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:

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
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc