Proration
When a subscription starts (or changes) part-way through a billing period, the
partial period is prorated. Proration is computed on calendar days, never
a fixed 30-day month: the factor is overlapDays / periodDays for the period in
question.
Modes
prorationBehavior chooses how a partial period is settled. You pick it both
when you assign a subscription (the partial period
from startDate to the billing-cycle anchor) and on the
mid-cycle changes that re-bill a partial period —
a plan replacement or products edit — where it's chosen in the UI
alongside the change. The same three modes apply in both cases:
| prorationBehavior | Behavior |
|---|---|
create_prorations | Add proration line items to the next invoice — the partial period from the start date to the billing-cycle anchor is charged when the first regular invoice is generated. |
always_invoice | Charge the partial period immediately on its own invoice, then bill regularly from the anchor. |
none | No proration — the partial period is gifted; regular billing begins at the anchor. Default. |
advance-billed subscriptions honor all three modes; arrears subscriptions
always prorate (they bill the period actually consumed).
Worked example
A 200.00/month plan, billed monthly in advance, starts on 11 July with the
billing-cycle anchor on the 1st. The first partial period is 11–31 July =
21 days of 31, so the factor is 21 / 31 ≈ 0.677 → 135.48.
prorationBehavior | First charge | Then |
|---|---|---|
create_prorations | the 135.48 is added to the next invoice (1 Aug), alongside the regular 200.00 | regular 200.00 on the 1st |
always_invoice | 135.48 billed immediately on its own invoice | regular 200.00 on the 1st |
none (default) | nothing — 11–31 July is gifted | regular 200.00 on the 1st |
Mid-cycle changes
A plan replacement or products edit part-way through a period re-bills the
affected partial period, settled by the prorationBehavior chosen for that change
(the same three modes above). The engine doesn't compute a delta: it splits the
timeline into a new segment and bills the new
segment's full charge minus what was already billed for the overlap, reconciled
through the ledger. Re-running the same change is idempotent — the ledger dedup
nets it to zero. A direction change or cancellation carries no products, so no
proration choice applies to it.
For advance subscriptions, a change that leaves the period under-billed (e.g. a
mid-cycle upgrade) is settled with a proration adjustment before the next regular
period, positive or negative. Cancellation refunds are a separate setting — see
Change flows → Cancel.