Reintroduces billing thresholds

What’s new

The billing_thresholds parameter, which was deprecated in the legacy usage-based billing deprecations in 2025-03-31.basil, is no longer deprecated.

Impact

You can use the billing_thresholds parameter in the subscriptions and invoicing API again as of version 2025-03-31.basil. The aggregate_usage parameter, legacy usage records endpoints, and legacy usage-based prices are still unavailable on newer API endpoints.

Changes

Parameter	Change	Resources or endpoints
billing_thresholds	Added	Invoice#create_preview.schedule_details.phases[]Invoice#create_preview.schedule_details.phases[].items[]Invoice#create_preview.subscription_details.items[] + 20 more QuotePreviewSubscriptionSchedule.default_settings QuotePreviewSubscriptionSchedule.phases[]QuotePreviewSubscriptionSchedule.phases[].items[]Subscription Subscription#create Subscription#create.items[]Subscription#update Subscription#update.items[]SubscriptionItem SubscriptionItem#create SubscriptionItem#update SubscriptionSchedule#create.default_settings SubscriptionSchedule#create.phases[]SubscriptionSchedule#create.phases[].items[]SubscriptionSchedule#update.default_settings SubscriptionSchedule#update.phases[]SubscriptionSchedule#update.phases[].items[]SubscriptionSchedule.default_settings SubscriptionSchedule.phases[]SubscriptionSchedule.phases[].items[]

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-05-28.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.