Stripe Billing Mode

Where the mode comes from when you do not choose one

Most subscriptions get a billing mode without anybody deciding, and there are two different defaults depending on how the subscription was created.

Through the API, the default follows your integration version. Stripe: "For API version 2025-09-30.clover and later, the default is flexible. For earlier versions, the default is classic." A preview version, 2025-08-27.preview, and later previews behave the same way. That has a consequence worth planning for, and Stripe states it as a warning: upgrading your API version "changes the default billing mode for new subscriptions from classic to flexible", so an upgrade nobody framed as a billing change quietly changes how new subscriptions calculate prorations, handle trials and process cancellations. To keep the old behaviour after upgrading you have to set the mode explicitly.

Through the Dashboard, the default comes from a setting instead, under Settings, then Billing, then Subscriptions and emails. It offers three choices: classic selected by default with both modes shown, flexible selected by default with both shown, or flexible only with classic hidden. Stripe is precise about the reach of that setting: it "only applies to new subscriptions created in the Dashboard. It doesn’t affect subscriptions created using the API or subscriptions migrated to flexible mode." Payment Links and Pricing Tables created in the Dashboard follow it too.

And for anyone who was already using Stripe Billing before flexible arrived, Stripe says the account default "is preserved as classic to maintain backward compatibility with your current integration". Nothing was migrated on your behalf.

How to tell which mode a subscription is on

The subscription carries the answer. Read the billing mode field on the subscription itself, which reports classic or flexible, and which also records the timestamp of a migration when one has happened. In the Dashboard the same value appears on the subscription, under Advanced settings when you update it.

The habit worth forming is to check the subscription rather than the account. There is no single account-wide answer to read, and there is no reason to expect a book of business built over several years to be uniform. If you are diagnosing why two customers on the same plan received different documents, this is the first field to look at, and it very often ends the investigation.

One related setting sits inside flexible mode rather than beside it. Flexible subscriptions can display proration discounts as itemized, which Stripe recommends and describes as showing "prorations with gross amounts and accurate discount amounts, consistent with non-prorations", or as included, the older display behaviour using net amounts and zero discount amounts. It changes what a proration line looks like on the invoice, not what it costs.

The migration runs one way

You can move a subscription from classic to flexible, through the Dashboard or through Stripe’s migrate endpoint. You cannot move it back. Stripe states it without qualification: "You can’t migrate a subscription from flexible billing mode to classic billing mode."

The part that matters for the books is what a migration does not touch. Stripe: "The flexible behaviors take effect for all new activity on the subscription after migration. However, Stripe doesn’t recalculate any resources created before migration, including pending proration Invoice Items." So a migrated subscription is not retroactively a flexible subscription. It is a classic history followed by flexible behaviour, and the timestamp on the field is the boundary between them.

Stripe lists four consequences of migrating, and each one is a behaviour change rather than a preference: credit prorations use the original debited amount instead of current subscription values, usage-based billing charges at the price in effect when the usage was reported, the billing cycle anchor is never automatically reset, and the move cannot be reversed.

Two practical notes. Working with flexible subscriptions through the API requires your integration to be on Stripe API version 2025-06-30.basil or later, though Stripe says the Dashboard can create one or migrate an existing subscription regardless of your version. And a subscription with an active schedule can only be migrated through the API rather than the Dashboard, in which case Stripe updates the schedule’s billing mode to match.

What actually differs, and where to read the detail

Billing mode is not a formatting preference, and the differences are specific rather than general. Stripe maintains a comparison page for the full list. Four of them have practical accounting consequences, and each is covered properly elsewhere on this site rather than summarised badly here.

Prorations and backdating. The mode decides whether a backdated period arrives as a single prorated line or as one line per natural billing period.

Usage-based pricing. On a mid-period price change, flexible bills usage at the price in effect when it was reported, and classic bills only usage reported since the current price took effect.

Mixed intervals. A subscription carrying items on different billing intervals requires flexible mode. Classic does not support it at all.

Trials and cancellations. Stripe names trial offers as a flexible-only capability, and lists cancellation processing among the behaviours that change on migration.

The common thread is that classic and flexible usually produce the same total and different documents. Since the document is what your accounting system receives, the mode is a bookkeeping question as much as a billing one.