Subscription proration calculator
calc_billing_prorationCredit 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.
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"period_start": "<period_start>",
"period_end": "<period_end>",
"change_at": "<change_at>",
"old_amount": "<old_amount>",
"new_amount": "<new_amount>"
},
"name": "calc_billing_proration"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| snap | No | 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 | nearest |
| options | No | Precision and rounding of the results (default: rounding=half_up, decimals=2). | |
| change_at | Yes | When the plan changes (Stripe's proration_date). Must be within the period. | |
| new_amount | Yes | What the new plan costs for a full period. 0 when cancelling or removing an item. Allowed: >= 0 and <= 1000000000000000. Unit: currency. | |
| old_amount | Yes | 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. | |
| period_end | Yes | End of the current billing period (the next renewal). | |
| granularity | No | 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 | exact |
| period_start | Yes | Start of the current billing period, ISO 8601 (2026-04-01T00:00:00Z). A time without an offset is read as UTC. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| inputs | Yes | The inputs as understood. | |
| result | Yes | ||
| formula | No | ||
| receipt | No | Only with ?receipt=true: a signed receipt for this answer, a JSON Web Token signed with Ed25519 (alg EdDSA). Its claims are iss, iat, jti (the request id), endpoint, date and response (this response without the receipt). Check it with the keys at /.well-known/jwks.json or POST /v1/receipts/verify. | |
| warnings | Yes | ||
| exactness | Yes | For each decimal output: exact; rounded (correctly, to the precision); rounded_uncertified (the last digit could not be proven); or underflow (below 1e-100, reported as 0). | |
| precision | No | The precision and rounding that were applied. | |
| calculator | Yes | The calculator and version that ran. | |
| references | No |