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 charge on the Product Plan.
  • The two plans need to share at least one Anchor Code on one of 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.

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

Product Plan AProduct Plan B
Product Plan Charge 1
Type: onetime
Anchor code: PPC1
Price: 1000 USD
Product Plan Charge 1
Type: onetime
Anchor code: PPC1
Price: 1000 USD
Product Plan Charge 2
Type: recurring
Anchor code: PPC2
Billing schedule: monthly
Price: 100 USD
Product Plan Charge 2
Type: recurring
Anchor code: PPC2
Billing schedule: quarterly
Price: 300 USD

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.

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: nxt' \
  --header 'authorization: Bearer {{Base 64-encoded API-Key}}' \
  --header 'content-type: application/json' \
  --data '
  	"Prorate": {
    "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 current plan and the new plan has the same billing cycle they will retain the same billing cycle and start and end date.

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.


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.