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

Removes legacy usage-based billingBreaking changes

What’s new

We’ve removed support for legacy usage-based billing. You can no longer create a price with a usage_type of metered without a specified meter. We’ve also removed the billing_thresholds from the subscription endpoints.

We’ve removed billing_thresholds and aggregate_usage from all API endpoints. You can no longer create legacy usage-based prices or attach existing legacy usage-based prices to quotes, upcoming invoices, or subscriptions.

A legacy usage-based price is defined as a price with a usage_type of metered without a specified meter.

Why is this a breaking change?

  • Removed billing_thresholds from Subscription endpoints.
  • Removed aggregate_usage from Price endpoints.
  • Using usage_type of metered without a specified meter now returns an error on Price creation.
  • Removed support for attaching prices of usage_type=metered without a set meter to Subscriptions, Subscription Schedules and Quotes.

Impact

Follow our migration guide to update your integration to use meters.

Changes

ChangeResources
Removed
UsageRecordSummaryUsageRecord
Endpoints ChangeResources
createRemoved
UsageRecord
listRemoved
UsageRecordSummary
usage_record_summariesRemoved
SubscriptionItem
ParametersChangeResources or endpoints
aggregate_usageRemoved
Price.recurring
billing_thresholdsRemoved
Subscription#create.items[]Subscription#createSubscription#update.items[]Subscription#updateSubscriptionItem#createSubscriptionItem#updateSubscriptionItemSubscriptionSchedule#create.default_settingsSubscriptionSchedule#create.phases[].items[]SubscriptionSchedule#create.phases[]SubscriptionSchedule#update.default_settingsSubscriptionSchedule#update.phases[].items[]SubscriptionSchedule#update.phases[]SubscriptionSchedule.default_settingsSubscriptionSchedule.phases[].items[]SubscriptionSchedule.phases[]Subscription

Upgrade

  1. View your current API version in Workbench.
  2. If you use an SDK, upgrade to the corresponding SDK version for this API version.
    • If you don’t use an SDK, update your API requests to include Stripe-Version: 2025-03-31.basil
  3. Upgrade the API version used for webhook endpoints.
  4. Test your integration against the new version.
  5. If you use Connect, test your Connect integration.
  6. In Workbench, perform the upgrade. You can roll back the version for 72 hours.

Learn more about Stripe API upgrades.

Related changes

Was this page helpful?
YesNo