What is prorated billing on subscription upgrades?

Proration is what lets you upgrade mid-cycle without paying the full new-plan price on top of whatever you already paid for the current cycle. The system calculates the dollar value of your unused current-plan credits and subtracts it from the new plan price. You only pay the gap.

The actual formula

Here is what the proration code in transaction-utils.ts does, exactly:

usageRatio        = min( currentCreditsBalance / currentPlanTotalCredits, 1.0 )
unusedCreditValue = usageRatio × currentPlanPrice
upgradeCharge     = max( 0, newPlanPrice − unusedCreditValue )

Three things worth calling out:

• The usage ratio is capped at 1.0. If you have more credits than your current plan's base allocation (because of bonus credits or because you never used any), the ratio caps at 1.0. This means the maximum refund value through proration equals the full price of your current plan — not more, even if your bucket balance is technically higher.
• The charge is floored at zero. If your unused value happens to exceed the new plan price (rare, but possible in some bonus-heavy cases on a small upgrade), you do not get a negative charge — you pay zero today.
• The new plan replaces the current bucket. The unused-credit dollar value is what you get for the proration. The credit count itself does not carry over; the new plan's full allocation lands in your monthly bucket.

Worked example — typical case

You're on a 10,500-credit plan at $15/month. Halfway through the cycle you have 5,250 credits left. You upgrade to the 52,500-credit plan at $55/month.

• usageRatio = min(5,250 / 10,500, 1.0) = min(0.5, 1.0) = 0.5
• unusedCreditValue = 0.5 × $15 = $7.50
• upgradeCharge = max(0, $55 − $7.50) = $47.50

You pay $47.50 today, get a fresh 52,500-credit allocation, and the billing cycle resets to 30 days from the upgrade.

Worked example — when the cap kicks in

You're on the same 10,500-credit plan at $15/month, but you never used your credits this cycle and you also bought a 2,000-credit PAYG pack that bumped the monthly bucket. Now your monthly bucket reads 12,500 credits (more than the plan's 10,500).

• Raw ratio: 12,500 / 10,500 = 1.19 — over 100%
• usageRatio = min(1.19, 1.0) = 1.0 (capped)
• unusedCreditValue = 1.0 × $15 = $15.00 (the full current-plan price)
• upgradeCharge = max(0, $55 − $15) = $40.00

The cap exists to prevent gaming the proration with bonus credits — the maximum credit you get for upgrading is the full price of the current plan, not more.

What proration doesn't cover

A few things that proration does not apply to:

• Downgrades. Downgrades are scheduled for the next renewal date — no immediate calculation, no payment today. See downgrade your subscription.
• PAYG credits. Those are independent of the subscription. They sit in a separate bucket, never expire, and are not part of the proration math.
• Past-due renewals. If your subscription is in past_due because a renewal payment failed, the next charge is the full plan price (paid via the pending invoice), not a prorated amount. Proration only applies to active-state upgrades.

When you see the math vs. when it just happens

The proration calculation runs at the moment you select a higher plan on the Buy Credits page. The Upgrade Preview modal that opens shows you the full breakdown:

• Your current plan and price
• Unused credit count and its dollar value (after the cap)
• The new plan and price
• The amount you will be charged today
• The new next-billing date (30 days from the upgrade)

Read it back to yourself before confirming. The numbers in the modal are locked in for that specific upgrade attempt — if you wait an hour and start again, the calculation re-runs with whatever your balance is at that moment.

Common questions

Can I time an upgrade to maximize my proration credit?

Sort of. The maximum credit value happens right after a renewal lands (you have a full monthly allocation untouched). The minimum happens right before the next renewal (you've used most of the allocation already). If you upgrade right after a renewal, you get nearly the full current-plan price refunded against the new plan. If you upgrade right before a renewal, you get almost nothing — but you also used what you paid for, so the net cost is similar either way.

Why use credit count, not days remaining, for proration?

Because what you actually paid for is credits, not days. If you used your full monthly allocation in the first 5 days of the cycle, calendar-based proration would still refund you 80% of the plan price even though you got the full value. Credit-based proration tracks what you actually consumed.

Do bonus credits affect the proration?

Yes, through your bucket balance. If your plan grants 10,500 credits (10,000 base + 500 bonus) and you have 8,000 left, your usage ratio is 8,000 / 10,500 ≈ 0.76. The bonus is folded into the plan's total_credits for ratio calculation purposes. The cap means even very large bonuses do not let proration value exceed the full plan price.

What if I cannot afford the prorated upgrade charge?

Wait until your next renewal, then upgrade right after it — you get the maximum proration credit and the smallest immediate charge. Or buy a smaller upgrade (the next-larger plan rather than skipping two tiers). Or buy PAYG packs as needed instead of upgrading.

Next steps