Manage rate cardsPrivate preview

This guide describes how to update and maintain a usage-based billing setup that uses rate cards, including how to create distinct billing and service intervals, introduce new services to all subscribers, and set up pricing versions by user cohort.

Set up a separate billing cadence and service interval

You can provide customers with more frequent usage insights by assessing usage on a weekly basis (this is the service interval). However, to reduce administrative overhead, you might only want to generate invoices on a monthly basis (this is the billing cadence).

Defining the service interval and billing cadence separately gives you the flexibility to aggregate usage and provision access at one frequency (for example, weekly) but bill customers at another (for example, monthly). This can help to optimize your cash flow needs.

Roll out new services to all subscribers without code

If you launch a new feature with new pricing, you can roll out that pricing to all of your subscribers by adding a new rate to the rate card. All subscribers on the live version have access to the new service you added, and the new rate applies immediately.

When you add a new rate to your rate card, it’s immediately available to all subscribers on that version. Any usage reported against the new rate’s meter is priced according to this rate, even if you add it in the middle of a billing cycle. This lets you quickly launch new billable services (like a new AI model) without writing code.

To add new rates to your existing rate card through the Dashboard:

1. Go to the Rate cards page.
2. Select a rate card, then click Edit rate card.
3. Click to add a new rate.

Set up different pricing versions by user cohort

Rate cards use versioning to give you flexible pricing management. When you create a rate card, an initial live version is automatically set as the default for new subscribers. Adding new rates to a rate card doesn’t create a new version. Only modifying or deleting existing rates creates a new version. The original version remains live until you manually change the live version.

To offer different pricing to different customer cohorts:

1. Subscribe new customers to the current live version (default) of a rate card.
2. Create different versions for different customer segments.
3. Subscribe specific customers to older versions.

When you create a rate card subscription, you can specify which version to use:

curl -X POST https://api.stripe.com/v2/billing/rate_card_subscriptions \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "rate_card": "rcd_A",
    "billing_cadence": "bc_1",
    "rate_card_version": "rcdv_123"
  }'

If you don’t specify a version, Stripe automatically uses the current live version.

Migrate customers to new or updated rate cards

To change the version for an existing subscriber, you must cancel their rate card subscription and create a new one with the new version. You can migrate existing customers to a new rate card or to a new version of a rate card. To do this, cancel the current subscriptions that use the old rate card or rate card version. Then, subscribe your customers to the new rate card or rate card version.

Cancel rate card subscriptions

To cancel a rate card subscription:

• In the Dashboard, go to the Rate card subscriptions page and select the one you want to cancel. Click the overflow menu () to the right of the subscription and select Cancel.
• To use the API, make a request to the Cancel a rate card subscription endpoint:

curl -X POST https://api.stripe.com/v2/billing/rate_card_subscriptions/{{RATE_CARD_SUBSCRIPTION_ID}}/cancel \
  -H "Authorization: Bearer 
{{YOUR_API_KEY}}
" \
  -H "Stripe-Version: 2025-03-31.preview"