# Adds billing mode to control how prorations and invoices for subscriptions are calculated and orchestrated ## Novidades The new `billing_mode` parameter lets you enable more flexible behavior when you create [Subscriptions](https://docs.stripe.com/api/subscriptions/create.md?api-version=2025-04-30.preview), [Invoice Previews](https://docs.stripe.com/api/invoices/create_preview.md?api-version=2025-04-30.preview), [Checkout Sessions](https://docs.stripe.com/api/checkout/sessions/create.md?api-version=2025-04-30.preview), or [Subscription Schedules](https://docs.stripe.com/api/subscription_schedules/create.md?api-version=2025-04-30.preview). | **billing\_mode=classic** | **billing\_mode=flexible** | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Credit proration amounts are calculated based on the value of the subscription item’s *current* price, tax, quantity, and the last discounts used. This could lead to unexpected prorations when a customer’s tax rates change mid-cycle, debit prorations are disabled, or complex amount-off coupons are used. | Credit prorations are calculated based on the original amount previously debited to a customer. This improves proration calculations to take into account taxes, coupons, and billing cycle considerations. For example, credit prorations will now accurately credit back taxes based on the original debit (if tax rate changed mid-cycle) and credit prorations will not be issued if there was no debit. | | `subscription.trial_start` is unchanged when a subscription goes back to `trialing` state. | `subscription.trial_start` is updated to reflect the most recent trial start date. | | The [billing_cycle_anchor](https://docs.stripe.com/api/subscriptions/object.md?api-version=2025-04-30.preview#subscription_object-billing_cycle_anchor) is sometimes reset during other operations: - `billing_cycle_anchor` is reset to the `cancel_at` date when setting [cancel_at](https://docs.stripe.com/api/subscriptions/object.md?api-version=2025-04-30.preview#subscription_object-cancel_at) to a date before the next time the subscription cycles. - `billing_cycle_anchor` is reset to the current time when switching from a subscription with all 0 USD prices to a subscription with at least one price greater than 0 USD. - `billing_cycle_anchor` is reset to the current time when switching to a price with a different recurring interval. | [billing_cycle_anchor](https://docs.stripe.com/api/subscriptions/object.md?api-version=2025-04-30.preview#subscription_object-billing_cycle_anchor) isn’t reset during other operations: - `billing_cycle_anchor` doesn’t change when setting [cancel_at](https://docs.stripe.com/api/subscriptions/object.md?api-version=2025-04-30.preview#subscription_object-cancel_at) to a date before the next time the subscription cycles. - `billing_cycle_anchor` doesn’t change when switching from a subscription with all 0 USD prices to a subscription with at least one price greater than 0 USD. - `billing_cycle_anchor` doesn’t change when switching to a price with a different recurring interval. | Configuring `billing_mode` to `flexible` has limitations. Learn more about the limitations and how [billing mode enables flexible behavior for subscriptions](https://docs.stripe.com/billing/subscriptions/billing-mode.md). ## Impacto You can set `billing_mode` to be `flexible` on the following API methods that create a subscription: - [Create a subscription](https://docs.stripe.com/api/subscriptions/create.md?api-version=2025-04-30.preview) - [Create an invoice preview](https://docs.stripe.com/api/invoices/create_preview.md?api-version=2025-04-30.preview) - [Create a checkout session](https://docs.stripe.com/api/checkout/sessions/create.md?api-version=2025-04-30.preview#create_checkout_session-subscription_data-billing_mode) - [Create a subscription schedule](https://docs.stripe.com/api/subscription_schedules/create.md?api-version=2025-04-30.preview) ## Alterações #### REST API | Parameter | Change | Resources or endpoints | | -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_mode` | Added | [Checkout.Session#create.subscription_data](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data), [Invoice#create_preview.schedule_details](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [Invoice#create_preview.subscription_details](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [Quote#create.subscription_data](/api/quotes/create?api-version=2025-04-30.preview#create_quote-subscription_data), [Quote.subscription_data](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [Subscription#create](/api/subscriptions/create?api-version=2025-04-30.preview), [SubscriptionSchedule#create](/api/subscription_schedules/create?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview) | #### Ruby | Parameter | Change | Resources or methods | | -------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_mode` | Added | [Checkout::Session::CreateParams::SubscriptionDatum](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data), [Invoice::CreatePreviewParams::ScheduleDetail](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [Invoice::CreatePreviewParams::SubscriptionDetail](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [Quote::CreateParams::SubscriptionDatum](/api/quotes/create?api-version=2025-04-30.preview#create_quote-subscription_data), [Quote::SubscriptionDatum](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [Subscription::CreateParams](/api/subscriptions/create?api-version=2025-04-30.preview), [SubscriptionSchedule::CreateParams](/api/subscription_schedules/create?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview) | #### Python | Parameter | Change | Resources or methods | | -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_mode` | Added | [Invoice.CreatePreviewParamsScheduleDetail](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [Invoice.CreatePreviewParamsSubscriptionDetail](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [InvoiceService.CreatePreviewParamsScheduleDetail](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [InvoiceService.CreatePreviewParamsSubscriptionDetail](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [Quote.SubscriptionDatum](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview), [checkout.Session.CreateParamsSubscriptionDatum](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data), [checkout.SessionService.CreateParamsSubscriptionDatum](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data) | #### PHP | Parameter | Change | Resources or methods | | -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_mode` | Added | [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview) | #### Java | Parameter | Change | Resources or methods | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billingMode` | Added | [InvoiceCreatePreviewParams.schedule_details](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [InvoiceCreatePreviewParams.subscription_details](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [Quote.subscription_data](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [QuoteCreateParams.subscription_data](/api/quotes/create?api-version=2025-04-30.preview#create_quote-subscription_data), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [SubscriptionCreateParams](/api/subscriptions/create?api-version=2025-04-30.preview), [SubscriptionScheduleCreateParams](/api/subscription_schedules/create?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview), [checkout.SessionCreateParams.subscription_data](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data) | #### Node.js | Parameter | Change | Resources or methods | | -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `billing_mode` | Added | [Checkout.SessionCreateParams.subscription_data](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data), [InvoiceCreatePreviewParams.schedule_details](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [InvoiceCreatePreviewParams.subscription_details](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [Quote.subscription_data](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [QuoteCreateParams.subscription_data](/api/quotes/create?api-version=2025-04-30.preview#create_quote-subscription_data), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [SubscriptionCreateParams](/api/subscriptions/create?api-version=2025-04-30.preview), [SubscriptionScheduleCreateParams](/api/subscription_schedules/create?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview) | #### Go | Parameter | Change | Resources or methods | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `BillingMode` | Added | [CheckoutSessionSubscriptionDataParams](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data), [InvoiceCreatePreviewScheduleDetailsParams](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [InvoiceCreatePreviewSubscriptionDetailsParams](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [QuoteSubscriptionDataParams](/api/quotes/create?api-version=2025-04-30.preview#create_quote-subscription_data), [QuoteSubscriptionData](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [SubscriptionParams](/api/subscriptions?api-version=2025-04-30.preview), [SubscriptionScheduleParams](/api/subscription_schedules?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview) | #### .NET | Parameter | Change | Resources or methods | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `BillingMode` | Added | [CheckoutSessionSubscriptionDataOptions](/api/checkout/sessions/create?api-version=2025-04-30.preview#create_checkout_session-subscription_data), [InvoiceScheduleDetailsOptions](/api/invoices/create-preview?api-version=2025-04-30.preview#create_invoice_preview-schedule_details), [InvoiceSubscriptionDetailsOptions](/api/invoices/create_preview?api-version=2025-04-30.preview#create_create_preview-subscription_details), [Quote.SubscriptionData](/api/quotes/object?api-version=2025-04-30.preview#quote-subscription_data), [QuotePreviewSubscriptionSchedule](/api/quotes/preview_subscription_schedules/list?api-version=2025-04-30.preview), [QuoteSubscriptionDataOptions](/api/quotes/create?api-version=2025-04-30.preview#create_quote-subscription_data), [SubscriptionCreateOptions](/api/subscriptions/create?api-version=2025-04-30.preview), [SubscriptionScheduleCreateOptions](/api/subscription_schedules/create?api-version=2025-04-30.preview), [SubscriptionSchedule](/api/subscription_schedules?api-version=2025-04-30.preview), [Subscription](/api/subscriptions/object?api-version=2025-04-30.preview) | ## 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-04-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.2.0-beta.1](https://github.com/stripe/stripe-ruby/releases/tag/v15.2.0-beta.1) 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.2.0b1](https://github.com/stripe/stripe-python/releases/tag/v12.2.0b1) 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.3.0-beta.1](https://github.com/stripe/stripe-php/releases/tag/v17.3.0-beta.1) 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.2.0-beta.1](https://github.com/stripe/stripe-java/releases/tag/v29.2.0-beta.1) 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.2.0-beta.1](https://github.com/stripe/stripe-node/releases/tag/v18.2.0-beta.1) 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.2.0-beta.2](https://github.com/stripe/stripe-go/releases/tag/v82.2.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.2.0-beta.2](https://github.com/stripe/stripe-dotnet/releases/tag/v48.2.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).