Launch usage-based pricing models with rate cardsVersion bêta privée

Charge customers complex pricing models with rate cards and subscriptions.

You can use rate cards to offer complex pay-as-you-go pricing models, like:

Large number of usage-based prices: Model hundreds of pay-as-you-go usage-based prices and group them into a single rate card. Each price references a dedicated meter to track customer usage.
Subscribe customers to the rate card: Subscribe customers to a rate card with many prices in it using a single API call that references the rate card ID.
Launch new rates instantly: Add new prices for new features to existing rate cards and start reporting usage events. This lets existing customers use the new feature immediately.

Before you begin

Rate cards are currently in private preview and could change in shape and integration path before they’re generally available to all Stripe users.

Limitations

Rate cards only support usage-based pricing. Additional support for licensed pricing models is planned.
You can only create rate cards for v2 subscriptions.
Invoices are limited to 250 line items. Subscriptions with more than 250 line items generate multiple invoices.

Get started

To get started with rate cards:

Create a rate card, which represents a grouping for all of your usage-based prices.
Add prices to the rate card.
Set up billing cadence for the customer to define how to invoice your customers on a recurring basis.
Subscribe the customer to the rate card by passing in the rate card and the billing cadence.
Start recording customer usage of your product, then send usage events to Stripe. The customer gets invoiced on each cadence.
Launch new rates for new products to existing customers by adding the new price to the rate card.

How rate cards work

The following diagram shows core concepts of charging a customer based on usage consumption with rate cards:

Create a rate card

Provide an internal name, currency, pricing service interval, and tax behavior to create a rate card. The service interval specifies the rate at which a customer accumulates fees. The billing interval, defined by the billing cadence, determines when the customer is invoiced.

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",
  "internal_name": "PAYGO 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"
}

Add prices to the rate card

After you create a rate card, create your usage-based Price, and add each price to the rate card.

recurring.usage_type must be metered.
recurring.meter must reference a Meter object to record usage events.
tax_behavior must match your rate card’s tax_behavior.
recurring.interval must match the service_interval of the rate card.

Add each of your Prices to the rate card by using the following API request:

Price IDs v1

The Rate Cards API won’t accept Price IDs v1 after this private preview becomes generally available. At that time, this request will require passing the price data directly. Rate card behavior will not change.

Set up billing cadence for the customer

Before subscribing your customer to the rate card, define when and how often to create invoices for the customer by creating a billing cadence. When an invoice is created, the customer’s default payment method is automatically charged.

To create a billing cadence, create a Customer object. To test your integration and advance time, you can create a test clock and attach it to the customer.

The Payer resource represents the entity who pays for each invoice (not necessarily the customer who uses the usage-based rates). To create a payer for the customer, make the following request:

After you create a payer, create a billing cadence for them. The billing_cycle defines when and how often you automatically bill the payer. When creating a billing cadence, set the exact day and time for invoicing using the following API request:

Subscribe your customer to the rate card by passing the rate card and billing cadence in the following request. You can optionally pass a specific version of a rate card when subscribing a customer. If you don’t specify a version, the subscription applies the rate card’s live version.

Record customer usage

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.

Poll meter events before advancing test clocks

After sending meter events, wait for meter event aggregation to complete before advancing your test clock. Poll the meter event summary endpoint to confirm your usage has been processed, then advance the test clock to generate invoices based on the billing cadence.

Launch new rates

If you launch a new feature that charges a new fee based on usage, you can create a new Price and add that price to your rate card. After adding a new price to the rate card, all existing customers subscribed to that rate card can start using the feature. To send meter events without updating their rate card subscription, add your new Price to the rate card:

Note