curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

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

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).

InputTypeDescription
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.

ResultTypeDescription
creditdecimal (string)Credit for the unused time on the old plan (a positive number; the invoice shows it as a negative line). Unit: currency.
chargedecimal (string)Charge for the remaining time on the new plan. Unit: currency.
netdecimal (string)charge − credit: what the change adds to the invoice (negative: a credit). Unit: currency.
remaining_fractionstringExact fraction of the period left after the change, as a decimal or p/q.
remaining_secondsstringSeconds from the change to the period end.
period_secondsstringLength of the billing period in seconds.
effective_change_atstringThe 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

Requestcurl
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"
  }'
200 OKResponse
{
  "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)

Requestcurl
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"
  }'
200 OKResponse
{
  "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

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.