Breaking changes
Public preview

Consolidates billing mode configuration across Billing products Breaking changes Public preview

What’s new

We’ve unified the billing_mode parameter and field format across all billing endpoints. The billing_mode parameter now uses a consistent object format with a type field, replacing the previous string format. We’ve also consolidated the billing_mode_details field into the main billing_mode object.

Why is this a breaking change?

The billing_mode parameter and field changed from accepting a string value ( classic or flexible) to requiring an object with a type field (for example, {type: 'flexible'}). Additionally, the separate billing_mode_details field has been removed, and its updated_at property is now included directly in the billing_mode object.

Impact

You need to update your integration if you currently use the billing_mode parameter or access the billing_mode field in API responses.

Before:

{
 "billing_mode": "flexible",
 "billing_mode_details": {
 "updated_at": 1234567890
 }
}

After:

{
 "billing_mode": {
 "type": "flexible",
 "updated_at": 1234567890
 }
}

This change affects the following API endpoints and resources:

Create subscriptions
Create subscription schedules
Checkout Sessions
Quotes
Create a preview invoice

Changes

Parameter	Change	Resources or endpoints
billing_mode_details	Removed	Subscription
Fields	Change	From → to
Checkout. Session#create. subscription_data. billing_mode Invoice#create_preview. schedule_details. billing_mode Invoice#create_preview. subscription_details. billing_mode Quote#create. subscription_data. billing_mode Quote. subscription_data. billing_mode Subscription#create. billing_mode SubscriptionSchedule#create. billing_mode	Changed	`enum('classic'\|'flexible') → billing_mode`
Quote. subscription_data. billing_mode QuotePreviewSubscriptionSchedule. billing_mode Subscription. billing_mode SubscriptionSchedule. billing_mode	Changed	`optional → required`
QuotePreviewSubscriptionSchedule. billing_mode Subscription. billing_mode SubscriptionSchedule. billing_mode	Changed	`enum('classic'\|'flexible') → SubscriptionsResourceBillingMode`
Subscription#migrate. billing_mode	Changed	`literal('flexible') → billing_mode_migrate`

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-06-30. preview

Upgrade the API version used for webhook endpoints .
Test your integration against the new version.
If you use Connect, test your Connect integration .

Learn more about Stripe API upgrades.