Here's a question that sounds trivial and isn't. A customer is on Basic, 3 seats. On day 12 of a 30-day billing cycle they switch to Pro, 2 seats. How much do you charge them today, and what do they renew at next month?
If your first instinct was "new price times new quantity," you've already shipped the bug. That's the renewal amount, not what they owe now. The amount due today is a proration, and getting it wrong means either robbing the customer or robbing yourself — quietly, on every mid-cycle change, forever.
I wrote this logic for a real billing integration, covered it in comments, and I'm glad I did, because six months later I couldn't reconstruct it from memory. Here's the part no payment SDK gives you.
What proration actually means
The customer already paid for the full cycle up front. When they change plans mid-cycle, two things are true:
- They have unused credit on the old plan for the days remaining.
- They owe the cost of the new plan for those same remaining days.
What you charge today is the difference between those two. Not the new full price — just the delta for the slice of the cycle they haven't used yet.
So for our example, with 18 of 30 days remaining (60% of the cycle left):
- Unused Basic credit ≈ 60% of (Basic price × 3 seats)
- New Pro cost ≈ 60% of (Pro price × 2 seats)
- Charge today = new cost − unused credit
The next renewal then bills the full Pro × 2 at the normal cycle boundary. Two completely different numbers, and conflating them is the classic mistake.
The four cases, one of which "should never happen"
Once seats enter the picture, a single change can be any of four shapes, and they don't behave the same:
- Upgrade + more seats — charge the prorated plan delta on existing seats and the prorated cost of the new seats.
- Upgrade + fewer seats — charge the plan delta only on the seats that survive; the removed seats generate credit, not charge.
- Downgrade — typically costs 0 today. You don't refund mid-cycle cash; the lower price takes effect next renewal.
- First purchase — no proration at all, just a clean charge.
In my code one branch is commented "this should never happen given the UI… but it's supported if needed." That comment is doing real work. Defensive billing code that handles the impossible case is cheaper than a support ticket from the one customer who found a way to trigger it.
The trap that actually bit me: dates
The subtle bug wasn't the money math. It was making the new cycle start exactly where the old one ended.
You take the provider's NextBillingTime, and if you carry the time-of-day along with it, the new cycle and the old one drift apart by hours — enough to double-bill a fraction of a day or leave a gap. The fix was to collapse to a date (drop the time component entirely) so the boundary lines up cleanly. In .NET that's exactly what DateOnly is for. A whole class of off-by-a-few-hours billing weirdness disappears the moment you stop carrying the clock around.
The design call: compute, log, never surprise the user
The last decision was philosophical. Proration is the kind of calculation that, if it's ever wrong, is wrong in a way the customer notices on their card statement. So I didn't expose intermediate failures to the user at all. Every branch produces a computed result object — the amount, the case it took, the dates it used — and logs the inputs aggressively. If a charge ever looks off, I can replay exactly which path ran and why, instead of guessing from a stack trace.
That's the real lesson, more than the arithmetic: for money math, observability is part of the feature. The calculation that you can't reconstruct after the fact is the one that costs you a chargeback.
Takeaway
Mid-cycle subscription changes aren't "new price × quantity." They're a difference of two prorated amounts, branching into four cases, anchored to a date boundary you have to normalize by hand. Write it once, comment the impossible branch, log the inputs, and let DateOnly save you from the clock. Then never touch it again if you can help it.
Top comments (0)