Proration Scenarios
10 reference scenarios for our Subscription product's proration feature. See Proration for the rules behind them.
Each scenario documents the:
- trigger
- behavior
- math
- outcome
Mid-cycle upgrade - roll into next transaction
Trigger: plan_change | Behavior: create_prorations
$20 plan → $50 plan on day 13 of a 30-day cycle. Credit the unused portion of the old plan, charge the used portion of the new one. The net adjustment sits as a pending balance and is settled on the next billing date.
Math
| Days remaining | 18 / 30 |
| Credit (old plan) | $12.00 |
| Charge (new plan) | $30.00 |
| Net | +$18.00 (customer owes) |
Outcome: Next transaction on 2026-06-30 charges $50.00 (new plan) + $18.00 (pending net) = $68.00. The proration event flips from pending to applied with the transaction ID set.
Mid-cycle downgrade - roll into next transaction
Trigger: amount_change | Behavior: create_prorations
$50 plan → $20 plan on day 13 of a 30-day cycle. The customer ends up with a credit, which sits on the balance until next billing.
Math
| Days remaining | 18 / 30 |
| Credit (old plan) | $30.00 |
| Charge (new plan) | $12.00 |
| Net | −$18.00 (customer is credited) |
Outcome: Customer balance becomes −$18.00 (a credit). Next transaction on 2026-06-30: $20.00 − $18.00 = $2.00 charged.
Mid-cycle upgrade - settle immediately
Trigger: plan_change | Behavior: immediate_action
Same upgrade as scenario Mid-cycle upgrade - roll into next transaction, but the merchant chooses to settle now. We charge $18.00 as a standalone transaction synchronously.
Math
| Days remaining | 18 / 30 |
| Credit (old plan) | $12.00 |
| Charge (new plan) | $30.00 |
| Net | +$18.00 (customer owes) |
Outcome: immediate_charge_amount is calculated and charged immediately. If the charge is declined: status stays pending, $18.00 lands on the balance, but the plan change still goes through.
Change with behavior: none
Trigger: amount_change | Behavior: none
Merchant sends "proration_behavior": "none". No credit, no charge, no log entry. The new amount takes effect from the next billing cycle.
Math
| Credit | $0.00 |
| Charge | $0.00 |
| Net | $0.00 |
Outcome: Response includes the new amounts and proration_result is omitted.
Resume from pause - plan unchanged
Trigger: resume | Behavior: N/A
Paused on June 13 with 18 days remaining in the cycle, resumed on July 10. The customer already paid for those 18 days - nothing is re-charged.
Math
No math runs.
Outcome: next_bill_date = July 10 + 18 days = July 28. No charge.
First cycle - change recurring amount - no proration
Trigger: amount_change | Behavior: create_prorations
Subscription is in cycle 1, charged $10 (via initial_amount). On day 13, the merchant changes the recurring amount to $50. Cycle 1 is still governed by initial_amount - there is nothing in the current cycle to prorate.
Math
No math runs for a recurring-amount change in cycle 1.
Outcome: The $50 recurring amount takes effect from cycle 2 (2026-06-30) onward.
First cycle - plan switch - prorate on initial_amount
Trigger: plan_change | Behavior: create_prorations
First cycle, charged $10 (old plan's initial_amount). Switching to a new plan whose initial_amount = $40 and recurring = $50. The switch does not re-derive amounts, so the new values are sent in the same request. The first cycle is governed by initial_amount, so the proration runs on that.
Math
| Days remaining | 18 / 30 |
Credit (old initial_amount $10) | $6.00 |
Charge (new initial_amount $40) | $24.00 |
| Net | +$18.00 (customer owes) |
Outcome: Cycle 2 on 2026-06-30 is billed $50 (new recurring) + $18.00 (pending net) = $68.00. Cycle 3 onward: $50.00.
Change during a trial - always zero
Trigger: plan_change | Behavior: immediate_action
Subscription is mid-trial. There is no recurring charge yet, so there is nothing to prorate. Amounts are always zero regardless of which behavior the merchant selects.
Math
| Credit | $0.00 |
| Charge | $0.00 |
| Net | $0.00 |
Outcome: No money moves now. The first regular transaction after the trial uses the new plan's initial_amount, then its recurring amount from cycle 2 onward.
Plan update propagated to existing subscriptions
Trigger: plan_propagation | Behavior: create_prorations
The merchant raises the plan amount from $20 to $50 and sends update_subscriptions: true. The plan's proration behavior is create_prorations, so every active subscription on the plan is prorated on day 13 of its own cycle.
Math
| Days remaining | 18 / 30 |
| Credit (old plan) | $12.00 |
| Charge (new plan) | $30.00 |
| Net | +$18.00 (customer owes) |
Outcome: Each affected subscription gets its own pending event with trigger = plan_propagation. Subscriptions that were never charged, that are in their trial, or whose status is not active are skipped.
Downgrade rejected - next charge below the minimum
Trigger: amount_change | Behavior: create_prorations
A $10 subscription is lowered to $2 on day 13 of a 30-day cycle. The resulting next charge would not cover the processing and billing fees of the transaction.
Math
| Days remaining | 18 / 30 |
| Credit (old plan) | $6.00 |
| Charge (new plan) | $1.20 |
| Net | −$4.80 (customer is credited) |
Outcome: The request is rejected with 400 and the message The resulting charge is below the minimum chargeable amount. Nothing is changed on the subscription.