Subscription proration API
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.
POST https://api.curatedapi.com/v1/calc/billing/proration
- Version 1
- MCP tool
calc_billing_proration - Try it in the browser
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.
Formula
f = (period_end − change) ÷ (period_end − period_start); credit = old × f; charge = new × f; each rounded; net = charge − credit
- 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.
Inputs
Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).
| Input | Type | Description |
|---|---|---|
period_start required |
string | Start of the current billing period, ISO 8601 (2026-04-01T00:00:00Z). A time without an offset is read as UTC. |
period_end required |
string | End of the current billing period (the next renewal). |
change_at required |
string | When the plan changes (Stripe's proration_date). Must be within the period. |
old_amount required |
decimal (string) | 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. Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
new_amount required |
decimal (string) | What the new plan costs for a full period. 0 when cancelling or removing an item. Allowed: >= 0 and <= 1000000000000000. Unit: currency. |
granularity |
exact | hour | day | week default exact |
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 |
snap |
nearest | up | down default nearest |
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 |
options.rounding |
half_even | half_up | half_down | up | down | ceiling | floor | Rounding mode applied once to each result. Default half_up. |
options.decimals |
integer | Round results to this many digits after the decimal point. |
Result
Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.
| Result | Type | Description |
|---|---|---|
credit | decimal (string) | Credit for the unused time on the old plan (a positive number; the invoice shows it as a negative line). Unit: currency. |
charge | decimal (string) | Charge for the remaining time on the new plan. Unit: currency. |
net | decimal (string) | charge − credit: what the change adds to the invoice (negative: a credit). Unit: currency. |
remaining_fraction | string | Exact fraction of the period left after the change, as a decimal or p/q. |
remaining_seconds | string | Seconds from the change to the period end. |
period_seconds | string | Length of the billing period in seconds. |
effective_change_at | string | The change time used, in UTC: change_at, or the boundary it moved to. |
Examples
Stripe example: $30 to $60 on April 11 at 6:00, prorated to the second
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"
}'
{
"calculator": "billing/proration@1",
"result": {
"credit": "19.75",
"charge": "39.50",
"net": "19.75",
"remaining_fraction": "79/120",
"remaining_seconds": "1706400",
"period_seconds": "2592000",
"effective_change_at": "2026-04-11T06:00:00+00:00"
},
"exactness": {
"credit": "exact",
"charge": "exact",
"net": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"period_start": "2026-04-01T00:00:00+00:00",
"period_end": "2026-05-01T00:00:00+00:00",
"change_at": "2026-04-11T06:00:00+00:00",
"old_amount": "30",
"new_amount": "60",
"granularity": "exact",
"snap": "nearest"
},
"formula": "f = (period_end − change) ÷ (period_end − period_start); credit = old × f; charge = new × f; each rounded; net = charge − credit",
"references": [
{
"title": "Stripe: Prorations (by the second; preview invoice example)",
"url": "https://docs.stripe.com/billing/subscriptions/prorations"
},
{
"title": "Stripe: Prorate by custom interval (hour, day or week; rounding to boundaries)",
"url": "https://docs.stripe.com/billing/scripts/stripe-authored/proration"
},
{
"title": "Chargebee: Proration (millisecond- and day-based)",
"url": "https://www.chargebee.com/docs/billing/2.0/subscriptions/proration"
}
],
"warnings": []
}
The same change prorated by day (nearest day boundary)
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"
}'
{
"calculator": "billing/proration@1",
"result": {
"credit": "20.00",
"charge": "40.00",
"net": "20.00",
"remaining_fraction": "2/3",
"remaining_seconds": "1728000",
"period_seconds": "2592000",
"effective_change_at": "2026-04-11T00:00:00+00:00"
},
"exactness": {
"credit": "exact",
"charge": "exact",
"net": "exact"
},
"precision": {
"rounding": "half_up",
"decimals": 2
},
"inputs": {
"period_start": "2026-04-01T00:00:00+00:00",
"period_end": "2026-05-01T00:00:00+00:00",
"change_at": "2026-04-11T06:00:00+00:00",
"old_amount": "30",
"new_amount": "60",
"granularity": "day",
"snap": "nearest"
},
"formula": "f = (period_end − change) ÷ (period_end − period_start); credit = old × f; charge = new × f; each rounded; net = charge − credit",
"references": [
{
"title": "Stripe: Prorations (by the second; preview invoice example)",
"url": "https://docs.stripe.com/billing/subscriptions/prorations"
},
{
"title": "Stripe: Prorate by custom interval (hour, day or week; rounding to boundaries)",
"url": "https://docs.stripe.com/billing/scripts/stripe-authored/proration"
},
{
"title": "Chargebee: Proration (millisecond- and day-based)",
"url": "https://www.chargebee.com/docs/billing/2.0/subscriptions/proration"
}
],
"warnings": []
}
References
- Stripe: Prorations (by the second; preview invoice example)
- Stripe: Prorate by custom interval (hour, day or week; rounding to boundaries)
- Chargebee: Proration (millisecond- and day-based)
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.
Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.