# 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](/guides/subscriptions/assign) a subscription (the partial period
from `startDate` to the billing-cycle anchor) and on the
[mid-cycle changes](/guides/subscriptions/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:

{/* @codegen subscription-proration — generated by `pnpm docs:generate`; do not edit by hand */}

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

{/* @codegen-end subscription-proration */}

`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](/guides/subscriptions/data-model) 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](/guides/subscriptions/changes#cancel).