stripeapi versioningbreaking changesinvoluntary churn

Stripe Has Shipped Five Breaking API Versions Since 2024. Most Accounts Don't Feel the Risk Until They Finally Upgrade.

Stripe ships a breaking API version roughly every six months. An old integration that upgrades late can inherit several at once, breaking renewals quietly.

XY
16 November 2026 · 8 min read

Stripe's September 30 release — the first version inside Endive, this year's breaking-change release line — removed payment_method_types from Checkout and turned billing_cycle_anchor into an object. Its October 28 follow-up, additive by design, added a pause button to the customer portal and roughly forty other things we've covered individually on this blog over the past few weeks. What we haven't covered is the system connecting both releases: Endive is the fifth breaking-change version Stripe has shipped since September 2024, on a cadence that's remarkably close to clockwork, and the biggest risk it creates isn't either release on its own. It's whatever happens the day an integration that's been quietly pinned to an old version finally gets touched.

Key stat
5
Breaking-change Stripe API versions shipped since September 2024 — Acacia, Basil, Clover, Dahlia, Endive
Source: Stripe API changelog, docs.stripe.com/changelog

None of this is new or hidden — Stripe documents every version publicly and explains the model in its own release-process announcement. The part that's easy to miss is what the model implies: an integration that never touches its pinned version is completely safe from all five of these releases, forever. It's the integrations that eventually do upgrade — months or years after they were built — that take the full accumulated hit at once, and that upgrade often isn't a deliberate "let's modernize our Stripe integration" project. It's a side effect of something else entirely.

How Stripe's versioning model actually works

Every Stripe account is pinned to a specific dated API version the first time it makes a live API call. That version's behavior — every field name, every parameter, every default — stays exactly as it was indefinitely. Stripe doesn't force an upgrade. You either change your version explicitly in Workbench, or you don't, and your integration keeps working on day-one logic for as long as you want.

What changes on a six-month-ish cadence is the name of the next available version. The first dated release inside a new flora name carries the breaking changes; every release after that, within the same flora, is additive only, until Stripe needs to break something again and moves to the next name in the list.

ReleaseFirst breaking versionRepresentative breaking changes
Acacia2024-09-30New billing-alert filters; stricter Terminal consent modeling; new address-validation defaults for Issuing cards
Basil2025-03-31Removed total_count on lists; Checkout Sessions drop shipping_details; indefinite-duration coupons no longer allowed; legacy usage-based billing removed
Clover2025-09-30Flexible billing mode becomes the default for new subscriptions; currency_conversion field removed from Checkout Sessions; initCheckout becomes synchronous
Dahlia2026-03-25Legacy Stripe.js methods removed (handleCardPayment and others); Checkout init method renamed
Endive2026-09-30payment_method_types removed from Checkout Sessions, PaymentIntents, SetupIntents, and Elements; billing_cycle_anchor becomes a polymorphic object; payment request button deprecated

Compiled from Stripe's own changelog entries for each release (docs.stripe.com/changelog/acacia, /basil, /clover, /dahlia, /endive).

Days between Stripe's breaking API releases
Acacia → Basil182 days
Basil → Clover183 days
Clover → Dahlia176 days
Dahlia → Endive189 days

Source: calculated from Stripe's own first-breaking-version dates for each release.

Four gaps, 176 to 189 days apart, averaging almost exactly six months. That consistency is actually useful information — it means "upgrade review" belongs on a calendar, the same way a PCI self-assessment or a tax registration check does, rather than something you only think about when a Stripe support email mentions it.

The upgrade you didn't mean to make

Here's the mechanism that turns a routine maintenance task into an involuntary-churn event. Stripe's own SDK versioning documentation states it directly: each SDK version uses the API version that was current at the time that SDK version shipped, unless your code explicitly overrides it with a pinned Stripe-Version header. Most integrations don't override it — they call stripe.checkout.sessions.create(...) and let the SDK's default version apply.

That's fine as long as you never touch the SDK. But a dependency bump happens for all kinds of reasons that have nothing to do with wanting new Stripe features: a security advisory on a transitive package, a Node or Python runtime upgrade that requires a newer SDK major version, a new engineer running npm update without checking what moved. If your account has been sitting on Acacia since early 2025 and that bump pulls in an SDK release built for Endive, your next deploy doesn't adopt one breaking change. It adopts all of them — Basil's, Clover's, Dahlia's, and Endive's — in a single push, with no changelog diff review and no 72-hour rollback plan in place, because nobody on the team realized an API version upgrade happened at all.

We've written about individual breaking changes from this pattern before. The billing_cycle_anchor object change errors out old string-formatted values the moment you're on Endive. The removal of payment_method_types from Checkout means a renewal page that explicitly lists accepted payment methods can silently fall back to whatever your Dashboard has configured instead of what your code says. Both of those are real, specific, and fixable once you know to look for them. What's harder to fix is not knowing your version moved in the first place, because nothing in a typical CI pipeline flags "your effective Stripe API version just changed" as a reviewable diff.

Why this looks like a product bug, not a billing failure

Every other source of involuntary churn on this blog — failed cards, expired SEPA mandates, SCA friction — shows up in Stripe's own dashboard as a declined or disputed payment. A version-drift bug doesn't. If your renewal flow references a field that changed shape, or a parameter that stopped being accepted, the failure mode is usually a 400 error in your own server logs, or a silently-ignored parameter that just doesn't do what it used to. Nobody tags that as churn. It gets filed as "weird bug in the billing code," investigated days or weeks later, and by then an unknown number of renewals have failed for a reason that has nothing to do with the customer's card. That's the same quiet-attribution problem we described in how a crashed webhook handler creates churn you end up blaming on customers — the API surface is different, but the failure to notice is identical.

The accounts most exposed aren't the ones ignoring Stripe's changelog. It's the ones with a Stripe integration old enough, and stable enough, that nobody has opened the billing code in over a year. Stability is good until the day something unrelated forces a touch, and the touch arrives bundled with four releases of debt instead of one.

A version-upgrade checklist that actually catches this

  • Pin your version explicitly in code, rather than trusting whatever your SDK's default happens to be. This turns a silent SDK-driven version bump into a visible, reviewable line change in a pull request.
  • Diff every flora release between your current version and your target, not just the newest one. A two-year-old integration jumping straight to Endive inherits Basil's, Clover's, and Dahlia's breaking changes too.
  • Upgrade webhook endpoint versions separately and deliberately. Stripe versions webhook payloads independently from API requests, so a code-side upgrade doesn't automatically protect (or break) your webhook handlers, and vice versa.
  • Use the 72-hour rollback window as an actual canary period, not a forgotten safety net — watch error rates and failed-renewal counts specifically in that window, because that's the only time reverting is a one-click action instead of a hotfix.
  • Never bundle a version upgrade with unrelated feature work. If the PR that bumps your Stripe SDK also ships a new pricing page, you've made it much harder to tell which change caused a given failure three weeks later.

None of this requires exotic tooling — it's closer to the discipline most teams already apply to dependency updates on anything that touches payments, just extended to a part of the Stripe relationship that doesn't announce itself with a dashboard banner. If you're already auditing where involuntary churn hides in your billing stack, run the numbers on what even a handful of silently-failed renewals a month would cost with our churn calculator — version-drift failures are rare per account, but they tend to hit every account on the same deploy, which is a different risk profile than a scattering of declined cards. CancelFlow doesn't touch your Stripe API version directly, but it sits in the same renewal and cancellation path these breaking changes land on, which is exactly why it's worth checking that path end to end before assuming a failed renewal is always the customer's card.

Frequently asked questions

What is Stripe's flora-named API versioning model?+

Since September 2024, Stripe groups its breaking API changes into named releases — Acacia, Basil, Clover, Dahlia, and Endive, in that order. The first dated version in each release (for example 2025-03-31.basil) introduces breaking changes; every dated version after that within the same release is additive only. Stripe moves to the next flora name specifically because it's about to ship something backwards-incompatible. Your Stripe account is pinned to whatever version was active the first time you made an API call, and it stays on that version — with all its old behavior — until you explicitly upgrade it in Workbench or override it in your code.

Does upgrading my Stripe SDK change my API version?+

Yes, by default. Stripe's own SDK versioning documentation states it plainly: each SDK version uses the API version that was current at the time that SDK version was released, unless you explicitly override it. If your account has been pinned to an old version for a year and you bump your Node, Python, or Ruby Stripe package for an unrelated reason — a security patch, a new language runtime requirement — your requests can silently start using a much newer API version, carrying every breaking change accumulated since your last upgrade.

How long do I have to roll back a Stripe API version upgrade?+

72 hours. Stripe's upgrade workflow in Workbench lets you roll back to your previous API version for 72 hours after performing an upgrade. After that window closes, you're committed to the new version and have to fix forward rather than revert.

How do I find out what will break before I upgrade my Stripe API version?+

Read the changelog for every flora release between your current pinned version and your target version, not just the latest one — each release lists its breaking changes separately. Then test your full integration, including webhook endpoints (which have their own separate version setting) and any Connect integration, against the new version in test mode before flipping production traffic over.

Try CancelFlow

Stop losing subscribers today

One script tag. One function call. A live cancellation flow in under 10 minutes.

Start free trial →
← All postsHome