How switching subscription plans work?

You can update the plan linked to a subscription which is active. To allow switching from one plan to another you first need to add the second plan in upgrade, downgrade or crossgrade config of first plan.

Example:

A user might want to switch from a standard plan titled standard to premium plan titled premium. To allow switch from standard to premium plan, offering more benefits, first you need to add premium plan in upgradable plan list of standard plan as shown below

To switch to premium plan if a user has a standard subscription linked to plan standard:

Steps

Step 1.

In the response of Get All subscriptions check is_upgradable boolean value for standard subscription, true means the subscription is upgradable.

Step 2.

Use Get Subscription Switchable Plans to get a subscription with lists of upgradable, downgradable and crossgradable plans, this can be used to display list of switchable plans with prorated amount to the user.

Step 3.

Use ATJS get Payment Options to get payment options for switching by passing context type switch. This will return a list of functions (to proceed with switch) mapped with different payment providers.

To get all payment options irrespective of subscription plan:

switchPaymentOptions = AccessType.getPaymentOptions(null, null, 'switch')

To get payment options supported by subscription plan pass subscription plan object to the method:

switchPaymentOptions = AccessType.getPaymentOptions(null, subscription_plan, 'switch')

Step 4.

When user selects plan to switch to and selects payment provider, call switchPaymentOptions[<payment_provider>].proceed() method with arguments - switch_type (here “upgrade”), subscription_plan_id, subscriptionId

await switchPaymentOptions['razorpay'].proceed({ 
    "upgrade", subscription_plan_id: 76, subscriptionId: 123 
});

this makes Subscription switch Preview call

Step 5.

AccesstypeJS would handle further Subscription switch api call, the response of which can be used to display subscription switch status message.

Errors

Common error codes on switch preview failure:

subscription_switch_preview_bad_attempt: returned when switch preview fails due to invalid params

Common error codes on switch failure:

subscription_switch_bad_attempt: returned when switch fails

Note: The payment window may or may not appear after switch preview call, depending on payment gateway and type of subscription, usually paymemt gateways handle charging extra on upgrade for recurring plans.