Switching plans

Pricing, payment cycles and terms of subscriptions typically change state over time. This change can be hard to keep track of, and in an ever growing subscription business - it is a core requirement to be able to switch between these parameters.

Examples of switch options

• Moving from annual pricing to monthly or reverse.
• Moving from the standard plan to the enterprise plan.
• Moving from freemium or trial to a premium plan.

Product plans define these parameters, whilst subscription charges define the state of each product plans. To switch between plans, Upodi supports switching plans on different events. Example subscription renewal next charge date or on a given point of time through our API.

Preparing for switch plans

To effectively switch plans, a few things need to align for the plan to be able to switch. This includes:

• Currency of the product plan charges must be the same. If two plans need to be able to switch, all currencies must exist across both.
• The Anchor Code must be unique for each product plan charge on the Product Plan.
• The two product plans need to share at the same number of product plan charges, and matching Anchor Code on their charges.
• The two charges with matching Anchor Codes need to have the same Billing Period Alignment (Forward or Backwards billed)

🚧

Anchor & SKU Explained

Anchor code is not mandatory for a product plan charge. However for a switch plan to work, the anchor glues which charges should be aligned as the switch is conducted.

SKU may or may not be the same value. There is no requirement for SKU on a product plan charge, however when a finance systems is connected the SKU field is used to lookup the product of an invoice.

Example

The table below illustrates two product plans with two charges each. A one-time charge and a recurring charge.

In the example, switching from product plan a to product plan b will transfer state of amount, and next payment date for the product plan charge 2, as anchor code (PPC2) matches both plans. The result will be that the one-time charge has already been processed by product plan A, so the subscription will transition from a monthly billed to a quarterly billed plan.

❗️

Mismatching Anchor

Mismatching anchor codes will eliminate the option to switch plans. A subscription cannot transfer the state (quantity and billing cycle state) between two subscription charges without the needed anchor, specified on the product plan charge.

Methods to switch

You can configure a subscription to switch on renewal of a subscription. This will trigger the subscription to switch at point of renewal, transferring the amount of the matching product plan charges - this is the amount of the current charge.

If you want to force a switch, the Upodi API supports switching at a point in time. Read more here.

Switch with a Discount Code

In some cases you maybe want to provide the customer with a discount for switching, for example if they decide to upgrade to a higher tier of product plan. In order for the discount to only be taken into account in the calculation of the price of the new plan you can supply it directly in the switch plan call as such:

curl --request PUT \
  --url https://api-front.upodi.io/subscriptions/{SubscriptionID}/switchplan \
  --header 'accept: application/json; charset=utf-8' \
  --header 'x-version: {version}' \
  --header 'authorization: Bearer {Base 64-encoded API-Key}' \
  --header 'content-type: application/json' \
  --data '
  {
  	"Prorate": {
    	"Action":1,
      "PricingStrategy":0
    },
  	"ToPlanID":"{ProductPlanID}",
    "DiscountCode": "Upgrade-Plan-200222452"
  }'

Using the API

When you perform an immediate plan switch the system will automatically calculate whether this is an upgrade or downgrade of plan and charge the customer for any additional expenses that comes with the plan change. You can actively choose to disregard any proration in your switch of plans.

The plan switch can be performed by a call to our API. For example:

curl --request PUT \
  --url https://api-front.upodi.io/subscriptions/{SubscriptionID}/switchplan \
  --header 'accept: application/json; charset=utf-8' \
  --header 'x-version: {version}' \
  --header 'authorization: Bearer {{Base 64-encoded API-Key}}' \
  --header 'content-type: application/json' \
  --data '
  {
  	"Prorate": {
    	"Action":1,
      "PricingStrategy":0
    },
  	"ToPlanID":"{ProductPlanID}",
    "BookAndPayOptions": {
    	"PayUsingDefault": true
    }
  }'

Guid subscriptionId = Guid.Parse("1dda50ed-514b-48f1-a041-ff305b2a9c77");
Guid toProductPlanId = Guid.Parse("08a7f42e-34c6-4a66-acbb-937ccf0ac66d");

// setup client
UpodiService upodi = new UpodiService("8dd652e2-22fc-4cf1-9433-d3fcbdc3cf3c");

// switch to the product plan
bool success = upodi.Subscriptions.SwitchPlan(subscriptionId, toProductPlanId);

If the new billing cycle is longer than the current plan, the new plan billing cycle will align to the old billing cycle start date but have a new end date.

If the new billing cycle is shorter than the current plan, the new plan billing cycle will align to the old billing cycle start date and retain the old end date. In order to achieve this we stretch the new and shorter billing cycle to fit the old, and then it will continue with the new billing cycle after the end date.

In all of the above cases Upodi calculates whether the already paid (minus the already consumed) is higher or lower than the price of continuing on the new plan to the new end date. If there is a deficit, a new invoice will be generated for the missing amount.

When the current switch period is over the customer will continue normally on the new plan.

Calculating the Outcome

If you want to know what the switch plan result will be the easiest way is to use the PreviewMode on the switch plan call.

Example:

curl --request PUT \
     --url https://api-front.upodi.io/Subscriptions/id/switchplan \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "Prorate": {
    "Action": 2,
    "PricingStrategy": 0
  },
  "BookAndPayOptions": {
    "PayUsingDefault": true
  },
  "PreviewMode": true,
  "ToPlanId": "guid"
}
'

If the switch comes with a cost the response contains an invoice preview result, which would be the exact invoice result if sent with PreviewMode false or no parameter.

Questions?

We're always happy to help with code or other questions you might have! Search our documentation or contact helpdesk. You can also chat live with us using the Intercom icon.