Stripe Flexible Billing Mode Migration and QuickBooks
Flexible billing mode credits what was charged, delays some upgrade invoices and changes invoice lines. A worked example and what QuickBooks receives.
Stripe now recommends flexible billing mode for new and existing subscriptions, and for newer API versions it has quietly made it the default. Create a subscription on API version 2025-09-30.clover or later and it is flexible unless your code says otherwise. Older subscriptions stay classic until someone migrates them. So most Stripe accounts that have been billing for a while already hold both kinds, and the first time a bookkeeper notices is usually a downgrade credit that doesn't match last month's.
Migrating to Stripe flexible billing mode is not a cosmetic switch. It changes how credit prorations are calculated, when an upgrade gets invoiced, and how many lines an invoice carries. Totals often come out the same. The documents don't, and the documents are what your QuickBooks file receives.
Finalized Stripe invoices, in QuickBooks as Stripe billed them. With Acodei's Invoice Sync, a paid-plan feature, a finalized Stripe invoice becomes a QuickBooks invoice with every line reproduced as your mapping settings allow, and the payment is applied when the invoice is paid. Start a free trial.
This post covers what migration changes, a worked downgrade under both modes, the upgrades that stop invoicing immediately, the smaller changes that alter invoice lines, what QuickBooks receives before and after, and a checklist for migrating without surprising your month-end close.
What does migrating a Stripe subscription to flexible billing mode change?
Migrating moves one subscription from Stripe's original billing engine to the newer one. From that moment, credit prorations are calculated from what the customer was actually charged, usage is billed at the price in effect when it was reported, and the billing cycle anchor stops resetting by itself. The migration is per subscription and can't be undone.
Stripe's billing mode guide lists the consequences in four lines:
- "Credit prorations use the original debited amount instead of current subscription values."
- "Usage-based billing charges at the price in effect when usage was reported."
- "The billing cycle anchor is never automatically reset."
- "You can't revert a subscription from flexible billing mode back to classic billing mode."
Two boundaries matter for the books. First, nothing old is rewritten: "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." Second, the migration leaves a timestamp. After a migration through the API, Stripe says "the billing_mode.updated_at timestamp reflects when the migration occurred." That timestamp is the line between a subscription's classic history and its flexible future, and it is worth writing down in your close notes.
You can migrate in the Dashboard (Update subscription, then Advanced settings, then Billing mode) or with the migrate endpoint. Subscriptions with an active schedule are API-only: "The Dashboard doesn't support billing mode migration for subscriptions with active schedules." For the field itself and where the default comes from, see our Stripe billing mode glossary entry.
Credit prorations: the same downgrade, two different credits
This is the difference most likely to show up in a QuickBooks report, so it is worth working through with numbers.
Stripe's comparison page states the rule for each mode. Classic: "the credit proration amounts are calculated based on the value of the subscription item's current price, tax, quantity, and the last discounts used." Flexible: "these prorations use the original debited amount instead of current subscription values."
Those are the same number whenever the current price is the price the customer paid. They split apart when the price changed in between without a charge, which is exactly what happens when you move customers to a new price with proration_behavior=none.
A worked example
One customer, a 30-day billing period from April 1 to May 1:
- April 1. Renewal at the Pro price of $90. The customer pays $90.
- April 6. You move them to the new Pro price of $120 with
proration_behavior=none. No invoice, no charge. They will pay $120 from May 1. - April 16. The customer downgrades to Basic at $30 a month, with prorations. Half the period is left.
| Line on the April 16 proration | Classic | Flexible |
|---|---|---|
| Credit for unused Pro time | -$60.00 (half of the current $120 price) | -$45.00 (half of the $90 actually charged) |
| Charge for remaining Basic time | $15.00 | $15.00 |
| Net | -$45.00 | -$30.00 |
Under classic, the customer is credited $15 more than they paid for that half-month: the unused half of a $120 price they were never charged. Under flexible, the credit matches the April 1 debit. Stripe prorates to the second by default, so real figures shift by a few cents depending on the time of day.
Stripe's own prorations guide has the same shape with smaller numbers. A $10 plan is upgraded to $20 with no proration, then downgraded back. Classic "credits a third of the month for 20 USD (-6.67 USD), even though the customer never paid for the price_20_monthly price," and the invoice total is -$3.34. Flexible "creates a credit proration based on the last price billed for the subscription item," and the credit and debit cancel to $0.
Discounts move too. In Stripe's second example, a $5 coupon on a subscription with a $10 item and a $20 item, canceling the $10 item halfway produces -$2.50 under classic and -$4.17 under flexible, because flexible applies the coupon "proportionally to each subscription item during proration calculations instead of distributing them evenly."
Two things that help when you reconcile
Flexible credits can be traced. Stripe says credit proration invoice items include proration_details.credited_items "when Stripe can attribute the credit to its original debit," pointing at the debited invoice line items. When an auditor asks why a credit is $45 and not $60, the answer sits on the object.
Flexible can also produce more lines than you expect. "If the time period being credited was originally billed across multiple debits, Stripe generates multiple credit prorations: one for each corresponding original debit." A customer who changed plans twice in a month can produce two or three credit lines on the next invoice instead of one.
Neither mode refunds the credit by itself. Stripe's guide says "Negative prorations aren't automatically refunded and positive prorations aren't immediately billed, although you can do both manually." A net credit like the -$45 or -$30 above stays with the customer in Stripe until it is used or refunded, and a customer credit balance "automatically applies to the next finalized invoice to a customer."
Upgrades that no longer create an invoice right away
The second big change is about timing, and it moves revenue between dates.
Classic resets the billing cycle anchor in several situations. Stripe's comparison lists them: "switching a subscription to a different price with a different recurring interval, changing from zero-amount prices to non-zero prices, or moving cancel_at to a date before the next time the subscription renews." A reset starts a new period on the spot and, under classic, creates an invoice immediately.
Flexible doesn't reset the anchor for any of those. The case that catches bookkeepers is the free-to-paid upgrade. Stripe: "When a customer upgrades from a free plan to a paid plan, Stripe creates pending invoice items and includes them on the next billing cycle invoice. Stripe doesn't immediately generate an invoice or attempt a charge, giving you time to collect a payment method if needed."
In practice: a customer on a free plan anchored to the 1st upgrades to a $50 monthly plan on the 10th. Under classic, an invoice for a fresh period is finalized on the 10th. Under flexible, the charge for the 10th to the 1st waits as pending invoice items and lands on the renewal invoice on the 1st, alongside the next full month. Same customer, same plan, and the first paid invoice moves to a different date and possibly a different accounting month.
Stripe gives two ways to keep the old timing: "pass proration_behavior=always_invoice or explicitly reset the billing cycle anchor by setting billing_cycle_anchor=now." Even an explicit reset behaves differently. Stripe's billing cycle guide notes that in flexible mode "resetting the billing cycle anchor to now doesn't automatically generate a new invoice," and that "To trigger an invoice on a BCA reset, you must also set proration_behavior to always_invoice." Our post on billing cycle anchors and which period a Stripe invoice covers goes deeper on anchors.
If your integration relies on an immediate invoice after an upgrade, to grant access or to start a period in your own system, test it on a migrated subscription before you migrate the rest.
Smaller changes that alter the invoice lines
Several more differences change what an invoice contains. None of them changes much money, but each changes the lines a reviewer sees.
- One-time charges added during an update. Under flexible, adding only one-time items with
add_invoice_itemsandproration_behavior=always_invoiceno longer creates an invoice by itself. Stripe "creates pending invoice items," which "can appear on a later eligible invoice, including the subscription's renewal invoice." - Zero-amount usage lines. Adding a usage-based item under flexible doesn't create a $0 line, and "If the resulting invoice wouldn't contain any items, we don't generate one." Renewal invoices still list every usage item.
- Backdating. Flexible splits a backdated range into one line per billing period instead of a single line. Our post on backdating a Stripe subscription shows both versions.
- Usage at a changed price. Flexible bills earlier usage at the earlier price instead of dropping it. Stripe's example invoices $0.75 under classic and $1.75 under flexible. See usage billed at the price in effect when reported.
- Trial line descriptions. Flexible uses one format, "Free trial for {quantity} x {product name}," where classic used two. Anyone filtering invoice lines by description text needs to update the filter.
- Proration discounts. Flexible subscriptions can set
proration_discountstoitemized, which shows "prorations with gross amounts and accurate discount amounts." The default,included, keeps net amounts. - Item limits and mixed intervals. Flexible allows up to 100 subscription items instead of 20, and only flexible supports monthly and annual prices on one subscription.
Portal cancellations change too: under flexible, Stripe "uses cancel_at directly rather than cancel_at_period_end." Reports or webhooks that look only at cancel_at_period_end will miss flexible cancellations.
What QuickBooks receives before and after migration
Nothing in Acodei's product documentation says Invoice Sync treats the two billing modes differently, so read this section as what the documented invoice path does with whatever Stripe produces. What is documented is the invoice path. When a Stripe invoice is finalized, Acodei creates a QuickBooks invoice that reproduces every line item, and tax lines, as your mapping settings allow. When the invoice is paid, by a successful charge, by a manual payment per your settings, or by a credit balance offset, Acodei creates a payment receipt or credit memo and applies it to that invoice. That needs QuickBooks Automatic Application switched on.
Put that next to the changes above and the effect on your books follows:
- A different credit amount arrives as a different line. The -$60 or -$45 credit is reproduced as Stripe finalized it. Billing mode decided the number before the sync ever saw it.
- Pending items aren't in QuickBooks yet. Acodei's trigger is the finalized invoice. A flexible upgrade waiting as pending invoice items has nothing to sync until the renewal invoice that carries it is finalized.
- Credits used later show up on the later invoice. When a customer credit balance reduces a future invoice, Acodei by default includes the applied balance as a line on the QuickBooks invoice so it matches what Stripe charged. An admin setting can skip that line and post the full gross amount instead.
- Small totals depend on a setting. Stripe's $10 example nets to $0 under flexible. Whether an invoice with nothing due reaches QuickBooks is controlled by Enable $0 Invoices, an Acodei admin setting that is off by default, so by default that invoice doesn't sync. A net-negative invoice like the classic -$45 is worth checking by hand in your file the first time one appears.
The practical result is that two customers on the same plan can produce differently shaped QuickBooks invoices for the same action, simply because one subscription was migrated and the other wasn't. When an invoice looks wrong, check billing_mode on the subscription that produced it before anything else.
A checklist for migrating to flexible without breaking your close
- Inventory first. List subscriptions by
billing_mode. New API-created subscriptions may already be flexible, and the Dashboard has its own default setting, which also governs Payment Links and Pricing Tables created there. - Check your API version. Stripe says flexible needs version
2025-06-30.basilor later to use through the API, and upgrading to2025-09-30.cloveror later changes the default for new subscriptions from classic to flexible. - Settle pending prorations first. Stripe doesn't recalculate pending proration invoice items at migration. Migrating right after a renewal invoice, when nothing is pending, keeps the boundary clean.
- Migrate a test batch. Pick a few subscriptions, migrate them, and watch one full cycle of upgrades, downgrades and renewals in both Stripe and QuickBooks.
- Decide on upgrade invoicing. If you need an invoice at the moment of a free-to-paid upgrade, add
proration_behavior=always_invoiceto that flow. - Update filters and reports. Trial line descriptions,
cancel_at_period_endchecks and anything that counts invoice lines. - Handle schedules through the API. Subscriptions with active schedules can't be migrated in the Dashboard, and a schedule that hasn't started yet can't be migrated at all. Stripe says to cancel and recreate it as flexible.
- Record the date. Note each migration's
updated_attimestamp. It explains every before-and-after difference a reviewer will ask about.
Billing mode changes the invoices. Acodei syncs what Stripe finalizes. Acodei's Invoice Sync syncs finalized Stripe invoices to QuickBooks, reproducing their lines as your mapping settings allow, and applies each payment when its invoice is paid. Start a free trial.
FAQ
Should I migrate my Stripe subscriptions to flexible billing mode?
Stripe recommends it, and new features such as mixed intervals and trial offers are flexible-only. Migrate when you've checked the integration: test upgrades, downgrades and cancellations on a few subscriptions, confirm anything that expects an immediate invoice after an upgrade, and migrate when no proration items are pending. The move is one-way per subscription.
Can I switch a Stripe subscription back from flexible to classic?
No. Stripe states that you can't migrate a subscription from flexible billing mode to classic billing mode. If a migration surprises you, the fix is changing how you update the subscription, for example adding proration_behavior=always_invoice to upgrades, not reverting the mode.
Why is a downgrade credit smaller after migrating to flexible?
Flexible credits unused time at the amount the customer was actually charged, while classic credits it at the subscription's current price. If you changed the price without prorating before the downgrade, classic credits time at a price the customer never paid. Flexible credits the original debit, so the credit can be smaller and matches what was billed.
Does migrating to flexible billing mode change past Stripe invoices?
No. Stripe says flexible behavior applies to new activity after migration and that it doesn't recalculate anything created before, including pending proration invoice items. Invoices already finalized, and the QuickBooks records synced from them, stay as they were. Only invoices after the migration timestamp follow the new rules.
Why didn't a free-to-paid upgrade create an invoice in flexible mode?
Flexible doesn't reset the billing cycle anchor when a subscription moves from a zero-amount price to a paid one. Stripe creates pending invoice items and bills them on the next renewal invoice. To invoice at the moment of upgrade, pass proration_behavior=always_invoice or reset the anchor with billing_cycle_anchor=now.
The short version
Flexible billing mode is where Stripe is heading, and many accounts are already half migrated without deciding to be. The money mostly comes out the same. The documents don't: credits follow what was charged rather than the current price, upgrades wait for the renewal invoice, and several kinds of line appear or disappear. Your QuickBooks file mirrors whatever Stripe finalizes, so migrate on purpose, a batch at a time, at a clean period boundary, and keep the migration date where your reviewer can find it.
Automate your Stripe to QuickBooks sync
Save hours every month. Acodei automatically syncs your Stripe transactions, invoices, and payouts to QuickBooks Online.
14-day free trial · card required · cancel anytime
How Acodei handles this in your stack
Stripe QuickBooks Integration
See how Acodei syncs Stripe payments, fees, refunds, invoices, and payouts into QuickBooks Online automatically.
Or go straight to a capability
Advanced Product Mapping
Map Stripe products to QuickBooks with rule-based logic on product ID, price ID, metadata, and account. Set rule priority and extend mapping to refunds and fees.
Automated Invoice Sync
Bring Stripe invoices into QuickBooks and auto-apply payments and credit memos, with invoice numbering suffixes and quantity tracking to cut double-entry.
Multi-Currency Mastery
Sync Stripe transactions across currencies with automatic exchange rate handling and currency-specific customer records. Our team enables multicurrency on request, and zero-decimal currencies such as JPY are not supported.
Class Mapping
Map Stripe products to QuickBooks classes for scalable categorization and multi-entity reporting. Class tracking requires QuickBooks Online Plus or Advanced.
Historical Data Import
Backfill historical Stripe data into QuickBooks by month range. Preview volume and cost before syncing so reporting starts from a complete baseline.
How to Connect Stripe to QuickBooks Online
Connect Stripe to QuickBooks Online in minutes. Acodei links both accounts with secure OAuth and syncs payments, fees, refunds, and payouts automatically.
Reconcile Stripe Payments in QuickBooks
Reconcile Stripe in QuickBooks Online automatically. Acodei splits out fees, matches payouts to deposits, and keeps every charge audit-ready.
Related articles
Acodei Journal
Stripe Monthly to Annual Switch: What QuickBooks Receives
Acodei Content Team
Stripe Monthly to Annual Switch: What QuickBooks Receives
11/16/2026
Acodei Journal
Raising Prices on Stripe Subscriptions and QuickBooks
Acodei Content Team
Raising Prices on Stripe Subscriptions and QuickBooks
11/15/2026
Acodei Journal
Stripe Pending Invoice Items: Billing Between Renewals
Acodei Content Team
Stripe Pending Invoice Items: Billing Between Renewals
11/14/2026
Get more operational finance guides like this one
We will only send high-value product and finance content.