← Back to Docs
Recipe

Proration Math

How Meridian calculates partial-period charges when subscriptions change mid-cycle.

The Core Formula

prorated_amount = (unit_price × remaining_seconds) / total_period_seconds

When a plan upgrade or downgrade occurs, Meridian computes the unused portion of the current billing period as a credit and applies it against the new plan's cost for the remainder of the cycle.

Step-by-Step Example

  1. Determine remaining time. Customer on a $30/month plan upgrades 10 days in. Remaining: 20 days → 1,728,000 seconds.
  2. Calculate unused credit. ($30 × 1,728,000) / 2,592,000 = $20.00 credit.
  3. Prorate new plan. New plan is $60/month. Remaining portion: ($60 × 1,728,000) / 2,592,000 = $40.00.
  4. Net charge. $40.00 − $20.00 credit = $20.00 due immediately.

Edge Cases

  • ▸Same-day switch. Remaining seconds equal total period seconds; credit covers full old-plan cost.
  • ▸Downgrade with negative balance. Excess credit rolls to next invoice as account balance.
  • ▸Annual plans. Total period is 31,536,000 seconds (365 days). Same formula applies.
  • ▸Leap seconds. Meridian uses UTC epoch math; leap seconds are ignored for billing consistency.

API Behavior

The /api/billing/preview endpoint returns a proration object with credit, charge, and net fields in cents. Call this before confirming any mid-cycle change to surface the exact amount to the customer.

← Return to Docs