All packsSaaS Billing + Tax CoreSolve
stripe subscription proration edge cases upgrade downgrade
Upgrade now, downgrade later -- and mean it
Upgrades and downgrades need opposite proration behavior on purpose: charge the difference now on upgrade, never mid-cycle-refund on downgrade (D10).
What goes wrong
Plan changes need opposite proration behavior depending on direction, and getting it backwards either short-changes the business (an upgrade that defers its price difference to next invoice, so the customer used the better plan for free this cycle) or short-changes the customer (a downgrade that mid-cycle refunds instead of letting them keep what they already paid for).
Why agents get it wrong
Stripe's proration_behavior parameter takes the same handful of values for both directions, so nothing in the API forces a developer to think about upgrade and downgrade as needing different settings -- it's easy to pick one proration_behavior value and apply it uniformly, and both directions will "work" in the sense of not erroring.
What SaaS Billing + Tax Core pre-decides
D10 pins upgrades to proration_behavior: 'always_invoice' (charge the difference immediately) with payment_behavior: 'error_if_incomplete' (a failed charge must not silently apply the upgrade anyway), and pins downgrades to a two-phase subscription schedule with proration_behavior: 'none' -- the customer keeps what they already paid for, no mid-cycle credit notes or refunds.
Source: ARCHITECTURE.md D10