Subscription Switching

This guide explains how subscription switching works from a Customer Support and clinic operations point of view. It covers what patients see, how products are configured, and what the team should check when helping a patient switch plans.

What Subscription Switching Means

Subscription switching lets a patient move from one subscription product to another without editing the old subscription directly.

The system always creates a new subscription for the replacement product. The original subscription is only canceled after the replacement subscription is successfully charged.

This protects:

patient billing history
payoff tracking
fulfillment/shipping clarity
support visibility
refund/accounting records

Why Some Patients Cannot Switch Immediately

Some subscription products are financed. That means the patient receives the product at the start, but the total cost is recovered across multiple billing cycles.

Example:

Patient pays the first payment at checkout.
Product ships after checkout.
The next billing cycles may be payment recovery only.
No new shipment should happen during those recovery-only payments.

If the patient still has a recovery balance, the app may require them to either:

wait until the final recovery payment is completed, or
pay off the remaining balance first, if the product allows payoff switching.

Switch Types

Scheduled Switch

Use this when the patient wants to choose their next subscription now, but their current financed cycle is not fully paid yet.

What happens:

Patient chooses the replacement product.
The app saves a pending switch request.
The current subscription continues billing as normal.
After the final recovery payment succeeds, the system activates the replacement subscription.
The old subscription is canceled after the replacement subscription charge succeeds.

How to explain it:

Your switch is scheduled. Your current plan will continue until the remaining recovery payments are complete. After that, the new plan will start automatically.

Immediate Payoff Switch

Use this when the patient wants to switch now and the product allows paying off the remaining balance.

What happens:

Patient chooses the replacement product.
The app creates a separate payoff invoice for the remaining balance.
Patient pays the payoff invoice.
The app then creates and charges the replacement subscription separately.
The old subscription is canceled only after the new subscription charge succeeds.

How to explain it:

To switch today, the remaining balance on your current plan must be paid first. That payoff is separate from the first payment on your new plan.

Important: the payoff charge and the new subscription charge are separate. Do not tell patients they are combined into one charge.

Product Configuration

Configuration is handled in the CRM Store product editor.

Go to:

CRM -> Store -> Products

For each subscription product, look for the subscription switching settings.

Setting: Allow Subscription Switch

This controls whether patients can request a switch from this product.

Off: patients cannot switch from this product in the portal.
On: patients can see switch options if there is at least one eligible replacement subscription product.

Recommended default:

Keep this off unless the product should support switching.

Setting: Subscription Switch Mode

This controls how switching is allowed.

Available modes:

After Recovery Only
Allow Payoff and Switch Now

After Recovery Only

Choose this when patients should only switch after their current financed recovery balance is fully paid.

Patient experience:

they can schedule a switch
they cannot pay off and switch immediately
the new subscription starts after recovery is complete

Best for:

products where early switching should not be encouraged
products where payoff handling should stay manual or unavailable

Allow Payoff and Switch Now

Choose this when patients are allowed to pay the remaining balance and switch immediately.

Patient experience:

they can schedule a switch
they may also see Pay Off & Switch Now
if a balance remains, the app creates a payoff invoice first
after payoff payment, the app starts the new subscription

Best for:

products where early upgrades/downgrades are allowed
products where support wants a self-service payoff option

Product Phase Setup

The app uses product variants/phases to understand billing and recovery.

Important phase fields:

phase price
phase duration cycles
belugaVisitType

Current behavior:

a phase with belugaVisitType = none is treated as a recovery/no-consultation phase
recovery phases are payment-only and should not trigger a new consultation/shipment
product billing cadence comes from the product billing interval, not each phase

CS note: if the recovery balance or remaining payment count looks wrong, ask an admin/developer to verify the product phase setup.

What Patients See

On the patient subscriptions page, patients may see:

recovery payments paid vs total recovery payments
remaining payments
remaining balance
whether they can schedule a switch
whether they can pay off and switch now
pending switch request details
payoff order reference if a payoff was created
cancel switch request button

Button examples:

Schedule Switch
Pay Off & Switch Now
Switch Now
Cancel Switch Request

What CS Should Check Before Advising a Patient

Check these items:

Is the current subscription active or paused?
Is subscription switching enabled on the current product?
Which switch mode is configured for the current product?
Does the patient have remaining recovery payments?
Is there already a pending switch request?
Was a payoff order already created?
Is the payoff invoice paid?
Did the replacement subscription get created?
Was the old subscription canceled after the replacement charge succeeded?

Payoff Orders

A payoff order is created only for immediate payoff switching when the patient still has a recovery balance.

Payoff orders:

are separate from the replacement subscription order
should not create a shipment
should not create fulfillment work
exist only to collect the remaining balance from the old subscription

Payoff orders are labeled with metadata in the system. The important identifier is:

SUBSCRIPTION_SWITCH_PAYOFF

If a payoff order appears to be moving into fulfillment, escalate it. Payoff orders should not ship product.

Replacement Subscription Orders

After the payoff succeeds, or after scheduled recovery completes, the app creates a replacement subscription order.

Replacement orders:

are separate from payoff orders
charge the first payment for the new subscription
can move through the normal fulfillment/order process
are linked back to the switch request

The old subscription should be canceled only after the replacement subscription charge succeeds.

Common Patient Questions

Why do I have to pay a balance before switching?

Because your current plan was financed. You received the product first, and the remaining payments recover that product cost. To switch now, the remaining balance must be paid first.

Will I be charged twice?

For immediate payoff switching, there are two separate charges:

payoff for the remaining balance on the old plan
first payment for the new plan

They are separate on purpose so billing and support records stay clear.

Will the payoff send another shipment?

No. The payoff invoice is only for the remaining balance. It should not create a shipment.

When does my old subscription stop?

The old subscription is canceled after the new replacement subscription is successfully charged.

Can I cancel a pending switch?

Patients can cancel a pending switch request from the patient subscription page while it is still cancelable.

Troubleshooting

Patient does not see switch options

Check:

current product has switching enabled
current product is a subscription product
subscription status is active or paused
there is at least one other active subscription product available
there is no existing pending switch request

Patient sees schedule switch but not payoff switch

Likely reason:

product is set to After Recovery Only

To allow payoff switching, update the product switch mode to Allow Payoff and Switch Now.

Patient paid payoff but new subscription was not created

Check:

payoff invoice status is paid
payoff order has SUBSCRIPTION_SWITCH_PAYOFF metadata
switch request status
patient has a valid/default payment method for the replacement subscription charge

Escalate if the switch request is FAILED or if the replacement charge failed.

Switch request failed

Common causes:

missing payment method
gateway declined the replacement subscription charge
product configuration issue

Current behavior:

old subscription remains intact
old subscription is not canceled
payoff, if already paid, remains paid

Escalate to admin/development for retry or manual handling.

Payoff invoice should not be refunded automatically

If the payoff succeeds but the replacement subscription charge fails, do not assume the payoff should be reversed automatically. Escalate so billing/support can decide the correct next action.

Current Limitations

As of 2026-05-23:

patients can create and cancel switch requests in the patient portal
EMR can view switch state on subscription details
EMR does not yet have full switch action controls
staff retry tooling for failed switch requests is not yet built
payoff invoice id is stored in switch request metadata, not as a separate database field

CS Escalation Checklist

Escalate to admin/development when:

a payoff order appears to trigger fulfillment
a switch request is stuck in FAILED
a payoff was paid but the new subscription was not created
the patient was charged unexpectedly
the remaining balance looks incorrect
product switch settings are missing or confusing
the old subscription was canceled before the replacement subscription succeeded

Include these details when escalating:

patient name/email
current subscription id
current product name
target product name
switch request status
payoff order number, if any
payoff invoice status, if any
replacement order/subscription id, if any
screenshot or notes showing what the patient sees