Current Plan Setup

List customer subscriptions

To show the customer all their subscriptions use /customers/:customerId/subscriptions method.

You will get all the details, including the next payment price, period, payment method, offer title etc.

This endpoint will return all active and cancelled subscriptions.


Current plan card - MediaStore SDK

A subscription purchased via In-Apps cannot be managed in MyAccount, as it may cause unpredictable behavior. In such a case, we recommend showing information about a payment method and hiding options to unsubscribe and apply a coupon. See the example below.


Subscription bought via In-App - MediaStore SDK

Update customer subscription


This applies to both un-subscribe and re-subscribe the subscription

Once you listed all subscriptions, you can enable the customers to unsubscribe or resubscribe. For both of these cases use /customers/:customerId/subscriptions.

Apply customer survey

You can also apply a customer survey to find out why the customer is unsubscribing. Attach a “reason” from survey cancellationReason to collect this data (you will see them in the subscriber retention dashboard. You can also see cancellation reasons in the Subscription Report section in the dashboard.


Survey - MediaStore SDK

Apply coupon on customer subscription

Once all customer's subscriptions are listed, you can apply a coupon to a selected one. You can do it by using /customers/:customerId/subscriptions/:subscriptionId endpoint.


Apply coupon - MediaStore SDK

Subscription upgrade

Customers can change their plan to defined plans thanks to the Subscription Switch feature. This feature can be used to upgrade subscribers on the web from one subscription plan to another.


Please note that this document focuses only on subscription upgrade.


Proper configuration is required in the Dashboard.

The Broadcaster has to define possible upgrades for a plan in subscription switch settings.
The hierarchy should be clearly defined which plan can be upgraded to which one.

Step-by-Step Guide



  • If you’re using ready-made github components, the “Subscription Switch” screens will look as below.
  • If you have your own “My Account” implementation and use only our API endpoints, the actual look and feel depends on your implementation.

For more information on the two options see the Quick Start - Create your app section.

Follow the steps below to change a subscription plan:

Step 1: List Possible Switch Options
To list possible switches use: /customers/:customerId/subscription_switches/:offerId/availability.

A customer will see “change plan” options:


Change Plan Section - MediaStore SDK

Remember that switches can be unavailable for customers temporarily or permanently.

For example, a switch is unavailable if a plan is not supported in a customer’s country. Or if a customer is at the end of the billing cycle for their current plan and the payment has already started - then it needs to be finished before upgrade is possible.

The list of possible cases is presented in API Reference.

Step2: Select and Make a Switch

When a customer chooses which plan he/she wants to switch to, use endpoint /customers/:customerId/subscription_switches/:offerId to make a switch.

The customer will see the details of the change, including the new price:


Upgrade Details - MediaStore SDK

If the customer decides to change the plan, the confirmation message appears:


Change Plan Confirmation - MediaStore SDK

And when the customer returns to plan details, the new plan will be visible as in the example below. The customer will also receive a confirmation email.


New Plan - MediaStore SDK


If a customer makes a switch, even in the middle of the billing period, he/she will get access to the new, upgraded plan instantly, but he/she will be charged the new price on the next billing date.

We had many options for payment billing, however, delayed payment is adopted as the standard practice across the OTT industry. Mainstream OTT providers like Netflix adopted a similar strategy.

Pro-rata billing is another option, however, this logic would cause significant data issues with accounting and KPI reporting. Delayed payment simplifies the complex logic and keeps it simple for the end users.


Monthly Upgrade

Some quick FAQs

Some upgrade options are not available to me as a user - why?
There may be a few reasons, for example:

  • You’re approaching the end of your billing period and an authorisation request has been made on your subscription. You can’t upgrade until the payment is finished.
  • You may already have access to content in the plan that you want to upgrade to.
  • The plan may not be accessible in your country.

Where can you use the subscription upgrade feature?
It is supported only for the web platform. It's not supported in native applications, as they have a different configuration setup based upon the respective store settings.

Is the subscription switch API supported in any payment gateway?
Currently, it is supported in the following payment gateways:

  • Adyen
  • Paypal
  • Bambora
  • Moneris
  • Stripe

If you use a different payment method, upgrade options will be unavailable.

MediaStore SDK supports Adyen and Paypal Express Checkout by API (with Cleeng as Merchant of Record). But you can still use MediaStore MyAccount to upgrade when your customer bought something with a different gateway (eg. Moneris).

Is it possible for me as a user to switch to a free plan?
No, switching to a free plan is not supported.

What upgrade options are available?
Upgrade options depend on what a Broadcaster defines. So a switch between given plans is only available if a Broadcaster has configured it.

Do upgrade options depend on a country?
Yes, as a user you can only upgrade to the plan that is supported in your country,

Currently, I have a plan with a free trial, and I want to upgrade - what will happen?
The free trial period will be kept. You will be charged at the end of the trial period with the new price.

I would like to upgrade to a plan with a free trial - when will the payment be scheduled?
You won’t be able to use a free trial.

I have a coupon on my current subscription, what will happen if I upgrade to a new plan?
If a coupon is active on a subscription, you can't upgrade.


Not a MediaStore SDK user?

If you’re not using MediaStore SDK, but you would still want to use the Subscription Switch feature, or you want to use it for marketing campaigns, please check out here API Reference. You can use it with a custom front-end. Please also remember that you need to configure switch options in the Dashboard (see Prerequisites).

Did this page help you?