Consolidates billing mode configuration across Billing productsBreaking changes

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:

Changes

Parameter	Change	Resources or endpoints
billing_mode_details	Removed	Subscription
Fields	Change	From → to
Checkout.Session#create.subscription_data.billing_modeInvoice#create_preview.schedule_details.billing_modeInvoice#create_preview.subscription_details.billing_modeQuote#create.subscription_data.billing_modeQuote.subscription_data.billing_modeSubscription#create.billing_modeSubscriptionSchedule#create.billing_mode	Changed	`enum('classic'\|'flexible') → billing_mode`
Quote.subscription_data.billing_modeQuotePreviewSubscriptionSchedule.billing_modeSubscription.billing_modeSubscriptionSchedule.billing_mode	Changed	`optional → required`
QuotePreviewSubscriptionSchedule.billing_modeSubscription.billing_modeSubscriptionSchedule.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.
In Workbench, perform the upgrade. You can roll back the version for 72 hours.

Learn more about Stripe API upgrades.