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.

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

Command Line
curl -X POST https://api.stripe.com/v2/billing/rate_cards \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "display_name": "Alpaca AI",
    "service_interval": "month",
    "service_interval_count": 1,
    "currency": "usd",
    "tax_behavior": "exclusive"
  }'

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.

Command Line
curl -X POST https://api.stripe.com/v2/billing/metered_items \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "display_name": "Alpaca AI tokens",
    "meter": 
{{METER_ID}}

  }'

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

Command Line
curl -X POST https://api.stripe.com/v2/billing/rate_cards/
{{RATE_CARD_ID}}
/rates \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "metered_item": 
{{METERED_ITEM_ID}}
,
    "unit_amount": "100"
  }'

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

Command Line
curl -X POST https://api.stripe.com/v2/billing/rate_cards/
{{RATE_CARD_ID}}
/rates \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "metered_item": 
{{METERED_ITEM_ID}}
,
    "tiers": [
        {
            "up_to": 10,
            "unit_amount": "100",
            "flat_amount": "40"
        },
        {
            "up_to": 20,
            "unit_amount": "90",
            "flat_amount": "30"
        }
    ],
    "tiering_mode": "graduated"
  }'

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.

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.

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

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.

Command Line
curl https://api.stripe.com/v1/invoices/create_preview \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d billing_cadence={{CADENCE_ID}}

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