Plan Change (Upgrade/Downgrade)

The system allows customers to change their subscription plan with automatic proration calculation.

Change Types

Type	Description
upgrade	New plan is more expensive than the current one
downgrade	New plan is cheaper than the current one
lateral	Same value (feature change)

Change Timing

Timing	Description
immediate	Applies immediately, charges/credits the prorated difference
end_of_period	Schedules the change for the start of the next period

Proration

Proration Methods

Method	Description
full_proration	Credits the old plan and charges the new plan for the remaining time
partial_proration	Charges only the difference (upgrade only)
no_proration	No mid-cycle value adjustment

Calculation Formula

remaining_days = max(0, ceil((period_end - now) / 86400000))
total_period_days = ceil((period_end - period_start) / 86400000))

Full proration:
  credit = (old_price x remaining_days) / total_period_days
  charge = (new_price x remaining_days) / total_period_days

Partial proration (upgrade only):
  difference = new_price - old_price
  charge = (difference x remaining_days) / total_period_days

Net charge = charge - credit

Default Configuration

The plan change configuration defines the default behavior:

Setting	Default
Allow upgrade	Yes
Allow downgrade	Yes
Proration on upgrade	full_proration
Proration on downgrade	no_proration
Upgrade timing	immediate
Downgrade timing	end_of_period
Refund on downgrade	No
Credit on downgrade	Yes
Apply discount on change	Yes

Plan Change Rules

You can create specific rules to control transitions between plans:

Field	Description
Source plan	Current plan (null = any)
Target plan	New plan (null = any)
Change type	upgrade, downgrade, or lateral
Allowed	Whether the transition is allowed
Timing	Overrides the default timing
Proration method	Overrides the default method
Discount (%)	Percentage discount on the charge
Bonus days	Trial extension
Message	Reason if not allowed
Priority	Higher priority takes precedence

Rule Priority Order

1. Rule with source plan AND target plan (most specific)
2. Rule with only source plan
3. Rule with only target plan
4. Global rule (both null)

Change Preview

Before executing, you can preview:

• Whether the change is allowed
• Type (upgrade/downgrade/lateral)
• Prorated credit and charge amounts
• Final net charge
• Effective date
• Remaining days in the period

Executing the Change

Immediate Change

1. Validation and preview are calculated
2. A PlanChange record is created (status: pending)
3. Credit generated if prorationCreditSubcents > 0
4. Invoice generated if netChargeSubcents > 0
5. Subscription updated with the new plan
6. PlanChange marked as completed

Scheduled Change

1. A PlanChange record is created (status: scheduled)
2. On the effective date, the worker processes the change
3. Subscription updated with the new plan
4. PlanChange marked as completed

Limitation: The system keeps only one scheduled change at a time. A new scheduled change cancels the previous one.

Cancel Scheduled Change

Scheduled changes can be canceled before the effective date. The status changes to canceled and the reason is recorded.