# Consolidates billing mode configuration across Billing products

## 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:**

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

**After:**

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

This change affects the following API endpoints and resources:

- [Create subscriptions](https://docs.stripe.com/api/subscriptions/create.md?api-version=2025-06-30.preview)
- [Create subscription schedules](https://docs.stripe.com/api/subscription_schedules.md?api-version=2025-06-30.preview)
- [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions.md?api-version=2025-06-30.preview)
- [Quotes](https://docs.stripe.com/api/quotes.md?api-version=2025-06-30.preview)
- [Create a preview invoice](https://docs.stripe.com/api/invoices/create_preview.md?api-version=2025-06-30.preview)

## Changes

#### REST API

| Parameter              | Change  | Resources or endpoints                                                   |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `billing_mode_details` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| 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`                    |

#### Ruby

| Parameter              | Change  | Resources or methods                                                     |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `billing_mode_details` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                                                                                                                                                                                                                                                                                                        | Change  | From → to                                                       |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `Checkout::Session::CreateParams::SubscriptionDatum.billing_mode`, `Invoice::CreatePreviewParams::ScheduleDetail.billing_mode`, `Invoice::CreatePreviewParams::SubscriptionDetail.billing_mode`, `Quote::CreateParams::SubscriptionDatum.billing_mode`, `Quote::SubscriptionDatum.billing_mode`, `Subscription::CreateParams.billing_mode`, `SubscriptionSchedule::CreateParams.billing_mode` | Changed | `enum('classic'|'flexible') → billing_mode`                     |
| `Quote::SubscriptionDatum.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::MigrateParams.billing_mode`                                                                                                                                                                                                                                                                                                                                                    | Changed | `literal('flexible') → billing_mode_migrate`                    |

#### Python

| Parameter              | Change  | Resources or methods                                                     |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `billing_mode_details` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                                                                                                                                                                                                                                                                                        | Change  | From → to                                                       |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `Invoice.CreatePreviewParamsScheduleDetail.billing_mode`, `Invoice.CreatePreviewParamsSubscriptionDetail.billing_mode`, `Quote.CreateParamsSubscriptionDatum.billing_mode`, `Quote.SubscriptionDatum.billing_mode`, `Subscription.CreateParams.billing_mode`, `SubscriptionSchedule.CreateParams.billing_mode`, `checkout.Session.CreateParamsSubscriptionDatum.billing_mode` | Changed | `enum('classic'|'flexible') → billing_mode`                     |
| `Quote.SubscriptionDatum.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.MigrateParams.billing_mode`                                                                                                                                                                                                                                                                                                                                     | Changed | `literal('flexible') → billing_mode_migrate`                    |

#### PHP

| Parameter              | Change  | Resources or methods                                                     |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `billing_mode_details` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                            | Change  | From → to                                                                |
| ----------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------ |
| `Quote.subscription_data.billing_mode`                                                                            | Changed | `enum('classic'|'flexible') → QuotesResourceSubscriptionDataBillingMode` |
| `QuotePreviewSubscriptionSchedule.billing_mode`, `Subscription.billing_mode`, `SubscriptionSchedule.billing_mode` | Changed | `enum('classic'|'flexible') → SubscriptionsResourceBillingMode`          |

#### Java

| Parameter            | Change  | Resources or methods                                                     |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| `billingModeDetails` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                                                                                                                                                                                                                                                                                   | Change  | From → to                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | --------------------------------------------------------------- |
| `InvoiceCreatePreviewParams.schedule_details.billingMode`, `InvoiceCreatePreviewParams.subscription_details.billingMode`, `Quote.subscription_data.billingMode`, `QuoteCreateParams.subscription_data.billingMode`, `SubscriptionCreateParams.billingMode`, `SubscriptionScheduleCreateParams.billingMode`, `checkout.SessionCreateParams.subscription_data.billingMode` | Changed | `enum('classic'|'flexible') → billing_mode`                     |
| `QuotePreviewSubscriptionSchedule.billingMode`, `Subscription.billingMode`, `SubscriptionSchedule.billingMode`                                                                                                                                                                                                                                                           | Changed | `enum('classic'|'flexible') → SubscriptionsResourceBillingMode` |
| `SubscriptionMigrateParams.billingMode`                                                                                                                                                                                                                                                                                                                                  | Changed | `literal('flexible') → billing_mode_migrate`                    |

#### Node.js

| Parameter              | Change  | Resources or methods                                                     |
| ---------------------- | ------- | ------------------------------------------------------------------------ |
| `billing_mode_details` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                                                                                                                                                                                                                                                                                          | Change  | From → to                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `Checkout.SessionCreateParams.subscription_data.billing_mode`, `InvoiceCreatePreviewParams.schedule_details.billing_mode`, `InvoiceCreatePreviewParams.subscription_details.billing_mode`, `Quote.subscription_data.billing_mode`, `QuoteCreateParams.subscription_data.billing_mode`, `SubscriptionCreateParams.billing_mode`, `SubscriptionScheduleCreateParams.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` |
| `SubscriptionMigrateParams.billing_mode`                                                                                                                                                                                                                                                                                                                                        | Changed | `literal('flexible') → billing_mode_migrate`                    |

#### Go

| Parameter            | Change  | Resources or methods                                                     |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| `BillingModeDetails` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                                                                                                                                                                                                                                                | Change  | From → to                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `CheckoutSessionSubscriptionDataParams.BillingMode`, `InvoiceCreatePreviewScheduleDetailsParams.BillingMode`, `InvoiceCreatePreviewSubscriptionDetailsParams.BillingMode`, `QuoteSubscriptionData.BillingMode`, `QuoteSubscriptionDataParams.BillingMode`, `SubscriptionParams.BillingMode`, `SubscriptionScheduleParams.BillingMode` | Changed | `enum('classic'|'flexible') → billing_mode`                     |
| `QuotePreviewSubscriptionSchedule.BillingMode`, `Subscription.BillingMode`, `SubscriptionSchedule.BillingMode`                                                                                                                                                                                                                        | Changed | `enum('classic'|'flexible') → SubscriptionsResourceBillingMode` |
| `SubscriptionMigrateParams.BillingMode`                                                                                                                                                                                                                                                                                               | Changed | `literal('flexible') → billing_mode_migrate`                    |

#### .NET

| Parameter            | Change  | Resources or methods                                                     |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| `BillingModeDetails` | Removed | [Subscription](/api/subscriptions/object?api-version=2025-06-30.preview) |

| Fields                                                                                                                                                                                                                                                                                                                         | Change  | From → to                                                       |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | --------------------------------------------------------------- |
| `CheckoutSessionSubscriptionDataOptions.BillingMode`, `InvoiceScheduleDetailsOptions.BillingMode`, `InvoiceSubscriptionDetailsOptions.BillingMode`, `Quote.SubscriptionData.BillingMode`, `QuoteSubscriptionDataOptions.BillingMode`, `SubscriptionCreateOptions.BillingMode`, `SubscriptionScheduleCreateOptions.BillingMode` | Changed | `enum('classic'|'flexible') → billing_mode`                     |
| `QuotePreviewSubscriptionSchedule.BillingMode`, `Subscription.BillingMode`, `SubscriptionSchedule.BillingMode`                                                                                                                                                                                                                 | Changed | `enum('classic'|'flexible') → SubscriptionsResourceBillingMode` |
| `SubscriptionMigrateOptions.BillingMode`                                                                                                                                                                                                                                                                                       | Changed | `literal('flexible') → billing_mode_migrate`                    |

## Upgrade

#### REST API

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. 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](https://docs.stripe.com/api/versioning.md) to include `Stripe-Version: 2025-06-30.preview`
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Ruby

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Ruby SDK to [v15.4.0-beta.2](https://github.com/stripe/stripe-ruby/releases/tag/v15.4.0-beta.2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Python

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Python SDK to [v12.4.0b2](https://github.com/stripe/stripe-python/releases/tag/v12.4.0b2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### PHP

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your PHP SDK to [v17.5.0-beta.2](https://github.com/stripe/stripe-php/releases/tag/v17.5.0-beta.2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Java

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Java SDK to [v29.4.0-beta.2](https://github.com/stripe/stripe-java/releases/tag/v29.4.0-beta.2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Node.js

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Node SDK to [v18.4.0-beta.2](https://github.com/stripe/stripe-node/releases/tag/v18.4.0-beta.2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### Go

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your Go SDK to [v82.4.0-beta.2](https://github.com/stripe/stripe-go/releases/tag/v82.4.0-beta.2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).

#### .NET

1. [View your current API version](https://docs.stripe.com/upgrades.md#view-your-api-version-and-the-latest-available-upgrade-in-workbench) in Workbench.
1. Upgrade your .NET SDK to [v48.4.0-beta.2](https://github.com/stripe/stripe-dotnet/releases/tag/v48.4.0-beta.2)
1. Upgrade the API version used for [webhook endpoints](https://docs.stripe.com/webhooks/versioning.md).
1. [Test your integration](https://docs.stripe.com/testing.md) against the new version.
1. If you use Connect, [test your Connect integration](https://docs.stripe.com/connect/testing.md).
1. In Workbench, [perform the upgrade](https://docs.stripe.com/upgrades.md#perform-the-upgrade). You can [roll back the version](https://docs.stripe.com/upgrades.md#roll-back-your-api-version) for 72 hours.

Learn more about [Stripe API upgrades](https://docs.stripe.com/upgrades.md).