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

	Change	Resources
	Removed	UsageRecordSummary UsageRecord
Endpoints	Change	Resources
create	Removed	UsageRecord
list	Removed	UsageRecordSummary
usage_record_summaries	Removed	SubscriptionItem
Parameters	Change	Resources or endpoints
aggregate_usage	Removed	Plan#create Plan Price#create.recurring + 1 more Price.recurring
billing_thresholds	Removed	Invoice#create_preview.schedule_details.phases[].items[]Invoice#create_preview.schedule_details.phases[]Invoice#create_preview.subscription_details.items[] + 17 more Subscription#create.items[]Subscription#create Subscription#update.items[]Subscription#update SubscriptionItem#create SubscriptionItem#update SubscriptionItem SubscriptionSchedule#create.default_settings SubscriptionSchedule#create.phases[].items[]SubscriptionSchedule#create.phases[]SubscriptionSchedule#update.default_settings SubscriptionSchedule#update.phases[].items[]SubscriptionSchedule#update.phases[]SubscriptionSchedule.default_settings SubscriptionSchedule.phases[].items[]SubscriptionSchedule.phases[]Subscription

Upgrade

View your current API version in Workbench.
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
Upgrade the API version used for webhook endpoints.
Test your integration against the new version.
If you use Connect, test your Connect integration.
In Workbench, perform the upgrade. You can roll back the version for 72 hours.

Learn more about Stripe API upgrades.

Replaces Upcoming Invoice API methods with the Create Preview Invoice API