ReCurr Plus Tutorial Series — Part 4: Plan Switching

ReCurr Plus feature — Requires an active ReCurr Plus licence (RECPLUS-XXXX-XXXX-XXXX-XXXX).

Plan Switching lets customers upgrade or downgrade between subscription plans from their My Account page — without contacting support.

There are two ways a switch can take effect:

• Queued at next renewal (default). The change is stored and applied at the next renewal date, so the customer’s current billing cycle is never disrupted. This is the original behaviour and remains the default for every store.
• Immediate, pro-rated upgrades (v2.7.0, opt-in). When you enable Immediate plan switching in settings, an upgrade by a quarterly or annual customer takes effect straight away — ReCurr credits the unused portion of the current term and charges only the difference. Downgrades and lateral moves stay queued. This is covered in detail below.

Nothing changes unless you opt in. With the immediate-switch settings off (the default), plan switching behaves exactly as it always has — every change queues to the next renewal.

---

Before You Begin

• ReCurr Plus is installed and your Plus licence key is active
• You have at least two subscription products that you want to make switchable between (e.g., Basic and Pro plans)

---

How Plan Switching Works (Queued — Default)

1. You assign the same Plan Group slug to all products that customers can switch between
2. A customer on one of those products visits their subscription in My Account
3. They click Change Plan and see the available plans in the same group
4. They select a new plan and confirm
5. The change is queued — a pending switch is stored against the subscription
6. At the next renewal date, ReCurr applies the new plan: updates the billing amount, period, and product
7. The customer receives an email confirming the plan change has been applied
8. If the customer changes their mind before renewal, they can cancel the pending change from the same page

---

Step 1: Assign a Plan Group to Each Product

For each product that should be part of the same switchable group:

1. Go to Products > All Products and click Edit
2. In the General tab, scroll to the Plan Group field
3. Enter a Plan Group slug — a short, consistent identifier shared by all products in the group

Plan Group slug rules:

• Lowercase letters, numbers, and hyphens only (e.g., website-maintenance, hosting-plans)
• Must be identical across all products in the group — spelling and capitalisation must match exactly
• Each product can only belong to one group

Screenshot 1: Plan Group field with a slug entered (e.g., website-maintenance).

Repeat for every product in the group.

Plan Rank (optional — only needed for immediate switching)

Beside the Plan Group field is an optional Plan rank (optional override) field. It is only relevant when you use immediate pro-rated switching (below), where ReCurr needs to know which product is the higher plan to decide whether a change is an upgrade (immediate) or a downgrade (queued).

• Leave it blank (recommended) and ReCurr ranks plans by their monthly price — the plan that costs more per month is treated as the higher plan. For normally-priced stores (e.g., Standard R99 < Plus R159 < Pro R349) this is correct with zero setup.
• Set a rank (a positive whole number, higher = better plan) only if your prices don’t reflect your plan hierarchy — for example a legacy or loss-leader plan that is priced low but is actually the premium tier. When both products in a comparison have a rank set, the rank wins.

Note: ranking never uses the term price (e.g. an annual total) or a sale price — only the monthly list price. This keeps “which plan is bigger” cycle-independent.

Screenshot 1b: The “Plan rank (optional override)” field beside Plan Group, with its help text.

---

Step 2: Verify the Plan Group is Set on All Products

Before testing, confirm that all intended products have the same Plan Group slug:

Product	Plan Group
Website Maintenance – Basic	website-maintenance
Website Maintenance – Standard	website-maintenance
Website Maintenance – Pro	website-maintenance

Screenshot 2: Three products in the Products list, each with the same Plan Group slug visible in the admin table.

---

Step 3: Test the Customer Experience

As a test customer, or by logging in as a customer account:

1. Go to My Account > Subscriptions
2. Click View on an active subscription for one of the grouped products
3. A Change Plan button should appear in the subscription actions

Screenshot 3: Subscription detail page in My Account showing the “Change Plan” button.

4. Click Change Plan — the Change Plan page loads showing the other available plans in the group
5. Each available plan shows the product name, billing amount, and billing period
6. Select a plan and click Confirm Change

Screenshot 4: The Change Plan page showing available plans with pricing.

7. A confirmation message appears: “Your plan change has been queued and will take effect at your next renewal on [date].”

Screenshot 5: Confirmation message after queuing a plan change.

8. Back on the subscription detail page, a notice shows the pending change with an option to cancel it

Screenshot 6: Subscription detail page showing the pending plan change notice with “Cancel Change” option.

---

Step 4: What Happens at Renewal

When the next renewal runs:

1. ReCurr detects the pending plan change on the subscription
2. The new product’s billing amount and period are applied
3. The customer is charged the new amount via their stored card token
4. The subscription record is updated to the new product
5. A “Your plan has been updated” email is sent to the customer confirming the change

No manual action is required — this is fully automated.

---

Immediate, Pro-Rated Upgrades (v2.7.0 — opt-in)

By default every plan change queues to renewal. If you’d rather let customers upgrade instantly — and pay only the fair difference — turn on Immediate plan switching under Subscriptions → Settings → General.

When a change happens immediately vs queues

ReCurr classifies every requested change and only the ones below take effect immediately; everything else queues exactly as before:

Requested change	Result
Higher plan (upgrade), customer on a quarterly or annual term, paying by card	Immediate — pro-rated
Longer cycle on the same plan (e.g. monthly → annual), quarterly/annual customer	Immediate — pro-rated
Lower plan (downgrade)	Queued at renewal (unless you also enable immediate downgrades — see settings)
Shorter or same cycle on the same plan	Queued at renewal
Any monthly or weekly customer	Queued at renewal (nothing to pro-rate)
Manual EFT subscription	Queued — applied on the next EFT invoice

The plan tier always wins over the cycle: moving to a higher plan is an upgrade even if the new cycle is shorter, and moving to a lower plan is a downgrade even if the new cycle is longer.

How the pro-rata credit is calculated

The quarterly / annual discount is a reward for completing the term. When a customer switches away mid-term, they keep credit for the time they haven’t used — valued at the full monthly rate — and forfeit the unearned share of the discount:

credit = amount paid for the current term
         − (days elapsed × the plan's full monthly price × 12 ÷ 365)

• The credit is applied to the new plan’s price, and the customer is charged only the difference.
• If the credit is larger than the new plan’s price, nothing is charged — the leftover credit stays on the account and reduces the next renewal automatically.
• The credit can never go negative — a late-term upgrade simply charges the full new price with no credit (there is never a charge-back to the customer).
• If the customer configured no annual/quarterly discount, the formula reduces to a plain linear pro-rata with nothing forfeited.

Worked example — Standard Annual at R2,990 (list monthly R299), customer upgrades to Plus Annual (R4,990) in month 5:

Consumed:  5 months × R299  = R1,495  (valued at the full monthly rate)
Credit:    R2,990 − R1,495  = R1,495
Charged now: R4,990 − R1,495 = R3,495

The customer’s billing date resets to today, and the next annual renewal is 12 months away at the new R4,990 rate.

The R5 minimum (hold-back)

PayFast will not process a charge under R5.00. If the pro-rated difference would land between R0.01 and R4.99, ReCurr charges exactly R5 and holds the small balance back as credit against the customer’s next renewal — so the customer’s total cost is unchanged to the cent. The consent screen, order notes, and confirmation email all state this explicitly. A fully credit-covered switch charges R0 and involves no card payment at all.

What the customer sees

1. On the Change Plan page the customer selects a higher plan and a confirmation screen appears showing exactly what will happen — the credit for their unused time, the amount charged now (or “R0 — covered by your credit”), any R5 hold-back, and their new billing date.
2. The screen is explicit that the remaining free-month benefit on the current term is forfeited by switching early. The customer must accept before anything is charged.
3. On confirming, ReCurr charges the difference via the stored card, swaps the plan, resets the billing date to today, issues the new-tier licence key (and expires the old key), and emails a full breakdown.
4. If the charge fails, the switch is cancelled cleanly — the plan is unchanged and nothing is credited or charged.

Screenshot 6b: The immediate-upgrade confirmation screen showing the credit, amount charged now, R5 hold-back note (if any), and new billing date.

Screenshot 6c: The “Your plan has been upgraded” email showing the old/new plan, credit applied, amount charged, and new licence key.

---

Admin View: Pending Plan Changes

In ReCurr > Subscriptions, subscriptions with a pending plan change show a visual indicator. Click into the subscription detail to see:

• Current plan
• Pending new plan
• Date the change will be applied (next renewal date)

Admins can also cancel a pending change from the subscription detail view.

---

Upgrade vs Downgrade

Plan Switching handles both directions:

Scenario	Queued (default)	Immediate switching on
Upgrade (e.g., Basic → Pro)	New higher amount charged at next renewal	Applied now; pro-rata credit, difference charged (quarterly/annual card subs)
Downgrade (e.g., Pro → Basic)	New lower amount charged at next renewal	Still queued at renewal (unless immediate downgrades are also enabled)

With immediate switching off, the customer completes the current billing cycle at the existing rate and the change applies from the next cycle onwards — there is no pro-rata credit or charge.

Note: Mid-cycle pro-rata credit only applies when you enable Immediate plan switching (see above). With it off, all changes take effect at renewal with no credit or charge.

---

Important Notes

• Same billing period not required — A customer can switch from a monthly plan to an annual plan (or vice versa) as long as both are in the same plan group. The next renewal will be calculated based on the new plan’s billing period.
• Plan group = switchable set — Only products in the same group appear as options on the Change Plan page. Products in different groups (or with no group) are never shown.
• Customer cannot switch to their current plan — The current product is excluded from the Change Plan options automatically.
• Only one pending change at a time — If a customer queues a change and then queues another change before renewal, the latest change replaces the previous one.
• Cancelled subscriptions cannot switch plans — The Change Plan button only appears for active subscriptions.
• Variable products are not offered (v2.8.8) — Change Plan does not offer a variable product, or one of its options, as a plan to switch to (switching between a product’s options is not available yet). A change of that kind queued before 2.8.8 is not applied: the subscription renews on its current plan, and its Activity Log says so. For a subscription taken out on an option of a variable product, an immediate change values the time already used at that option’s price.
• The quantity is kept (v2.8.8) — on a subscription bought with a quantity above 1, the plans are shown, queued, charged and renewed at the price for every unit, and the credit for an immediate change values the time used for every unit.

---

Quick Checklist

• [ ] Plan Group slug assigned to all products in the group (identical slug on each)
• [ ] At least two products in the same group
• [ ] Products published and active
• [ ] Test customer has an active subscription on one of the grouped products
• [ ] “Change Plan” button visible in My Account subscription detail
• [ ] Plan change queued successfully — confirmation message shown
• [ ] Pending change visible with “Cancel Change” option
• [ ] Renewal processed — new plan applied, confirmation email received
• [ ] (Immediate switching) Enabled Immediate plan switching in settings and confirmed an upgrade applies now with the correct pro-rata credit and difference charged
• [ ] (Immediate switching) Confirmed the consent screen shows credit, amount charged now, R5 hold-back (if any) and the new billing date before charging
• [ ] (Immediate switching) Confirmed a downgrade still queues to renewal

---

What’s Next?

Up next: Plus Tutorial 5: Cancellation Refunds & Retention — pro-rata refunds when customers leave, and a retention “save” flow.

For the full core ReCurr tutorial series, start at Tutorial 1: Getting Started.

For billing and licence questions, contact us at the email address shown in your store’s subscription confirmation emails.

---

This is Part 4 of the ReCurr Plus Tutorial Series.

Tutorial	Topic
Plus 1. Billing Cycle Toggle	Monthly/annual toggle on one product
Plus 2. Flexible Trials	7/14/21/28-day trial options
Plus 3. Quarterly Discounts	Configuring quarterly pricing and discounts
Plus 4. Plan Switching	Plan groups, customer upgrades and downgrades (you are here)
Plus 5. Cancellation, Refund & Retention	Pro-rata refunds on cancel + retention save flow
Plus 6. Pause & Resume	Freeze a subscription and resume later
Plus 7. Variable Subscription Products	Sizes, plans and buy-once-or-subscribe as subscription options
Plus 8. Troubleshooting Variable Subscriptions	Every message, what causes it, where to look