curatedapi

Subscription proration calculator

Credit for unused time and charge for the remaining time when a subscription changes plan mid-period, prorated to the second like Stripe, or by hour, day or week.

Start of the current billing period, ISO 8601 (2026-04-01T00:00:00Z). A time without an offset is read as UTC.
End of the current billing period (the next renewal).
When the plan changes (Stripe's proration_date). Must be within the period.
What the old plan costs for a full period (price × quantity, after discounts). In Stripe's flexible billing mode, use what was actually billed for the period. 0 when adding a new item.
What the new plan costs for a full period. 0 when cancelling or removing an item.
Unit of time the proration is counted in. Options: exact: to the second (to the microsecond if the times have one), as Stripe and Chargebee do by default; hour: whole hours from the period start; day: whole days from the period start; week: whole weeks from the period start
With an hour, day or week granularity, which boundary the change time moves to. Options: nearest: the closer boundary; exactly halfway goes to the later one; up: the next boundary: the old plan runs for the whole unit; down: the previous boundary: the new plan applies for the whole unit
More options: rounding and decimals
Precision and rounding
Rounding mode applied once to each result. Default half_up.
Round results to this many digits after the decimal point.

Examples

Result: The same change prorated by day (nearest day boundary)

Credit
Credit for the unused time on the old plan (a positive number; the invoice shows it as a negative line).
20.00 exact
Charge
Charge for the remaining time on the new plan.
40.00 exact
Net
charge − credit: what the change adds to the invoice (negative: a credit).
20.00 exact
Remaining fraction
Exact fraction of the period left after the change, as a decimal or p/q.
2/3
Remaining seconds
Seconds from the change to the period end.
1728000
Period seconds
Length of the billing period in seconds.
2592000
Effective change at
The change time used, in UTC: change_at, or the boundary it moved to.
2026-04-11T00:00:00+00:00

Rounding: Half up, 2 decimal places. Calculator billing/proration@1.

How it is calculated

f = (period_end − change) ÷ (period_end − period_start); credit = old × f; charge = new × f; each rounded; net = charge − credit

When a customer changes plan part-way through a billing period, they are credited the unused part of what they paid for the old plan and charged the remaining part of the new one. Both are the full-period amount times the fraction of the period left: (period end − change time) ÷ (period end − period start). By default this is exact to the second, as Stripe and Chargebee prorate; with an hour, day or week granularity the change time first moves to a boundary counted from the period start, like Stripe's custom-interval proration. The credit and the charge are each rounded, and the net is charge minus credit, as on the invoice.

  • Times are compared as instants, so the result does not depend on time zones or daylight saving time; boundaries for hour, day and week granularity are counted from period_start, not from midnight, as in Stripe's custom-interval proration. A boundary past the period end counts as the period end.
  • Stripe's classic billing mode credits the old item at its current price; its flexible mode credits what was actually billed. Put the matching amount in old_amount.
  • The credit and the charge are rounded separately and the net is their difference, as Stripe and Chargebee show prorations on an invoice.
  • Amounts are rounded to the cent (2 decimals) half up by default, the usual commercial rule and the one Stripe Tax uses. Set options.decimals for currencies with other minor units (0 for JPY, 3 for KWD) and options.rounding for another rule.

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Use it from your code

POST /v1/calc/billing/prorationVersion 1
curl https://api.curatedapi.com/v1/calc/billing/proration \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z",
    "change_at": "2026-04-11T06:00:00Z",
    "old_amount": "30",
    "new_amount": "60",
    "granularity": "day"
  }'
The same call in Python
import os

import requests

payload = {
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z",
    "change_at": "2026-04-11T06:00:00Z",
    "old_amount": "30",
    "new_amount": "60",
    "granularity": "day",
}
response = requests.post(
    "https://api.curatedapi.com/v1/calc/billing/proration",
    headers={"Authorization": f"Bearer {os.environ['CURATEDAPI_KEY']}"},
    json=payload,
    timeout=10,
)
print(response.json()["result"])
The same call in JavaScript
const payload = {
    "period_start": "2026-04-01T00:00:00Z",
    "period_end": "2026-05-01T00:00:00Z",
    "change_at": "2026-04-11T06:00:00Z",
    "old_amount": "30",
    "new_amount": "60",
    "granularity": "day",
};
const response = await fetch("https://api.curatedapi.com/v1/calc/billing/proration", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CURATEDAPI_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});
console.log((await response.json()).result);

MCP tool calc_billing_proration at https://mcp.curatedapi.com. Inputs, outputs and errors in the API reference.

Put it on your website

<div data-curatedapi-widget="billing/proration" data-key="capi_public_…"></div>
<script src="https://widgets.curatedapi.com/v1/widget.js" async></script>

Use a public key registered for your site. Calculations are billed like API calls. How widgets work.

Related calculators

Preview and check subscription charges

Show customers the exact charge before they change plan, or check an invoice before it goes out. Proration, tiers and stacked coupons follow the rules Stripe uses, to the cent.

Free for up to 1,000 charges priced a month. 50,000 charges priced a month cost $9.00 on the Starter plan.