saas-prorate

Zero-dependency financial proration specifically for SaaS upgrades & downgrades.

Handling billing upgrades mid-cycle is mathematically annoying. You have to calculate the unused credit from the old plan, the remaining cost of the new plan, and the net difference—handling leap years, varying month lengths, and exact second-precision.

saas-prorate does this for you with a single function.

Installation

npm install saas-prorate

Usage

import { calculateSwitch } from 'saas-prorate';

// Example: User upgrades from Basic ($30) to Pro ($60) halfway through the month
const result = calculateSwitch({
  start_date: '2023-04-01', // Billing period start
  end_date: '2023-05-01',   // Billing period end
  switch_date: '2023-04-16', // When they hit "Upgrade"
  old_amount: 3000,          // $30.00 (in cents)
  new_amount: 6000,          // $60.00 (in cents)
});

console.log(result);
/*
{
  credit_amount: 1500,     // $15.00 unused on old plan
  charge_amount: 3000,     // $30.00 cost for remainder on new plan
  net_amount: 1500,        // $15.00 due immediately
  remaining_ratio: 0.5,
  ...
}
*/

API

calculateSwitch(input: ProrationInput): ProrationResult

Input

| Field | Type | Description | |---|---|---| | start_date | Date/string/number | Start of the current billing cycle | | end_date | Date/string/number | End of the current billing cycle | | switch_date | Date/string/number | (Optional) When the change happens. Defaults to now. | | old_amount | number | Cost of the CURRENT plan for the FULL period (integers preference) | | new_amount | number | Cost of the NEW plan for the FULL period (integers preference) |

Output

| Field | Type | Description | |---|---|---| | credit_amount | number | Value of the unused time on the old plan | | charge_amount | number | Value of the remaining time on the new plan | | net_amount | number | Amount due (charge - credit). Negative means refund. | | remaining_ratio | number | Precise fraction (0-1) of time remaining. |

Why use this?

• Precision: Uses millisecond-level math to determine ratios.
• Simplicity: No external dependencies.
• Safety: Robust validation preventing logical errors (like switching outside the billing period).

License

MIT