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 canceled subscriptions.

Note:
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.

Important note for seasonal subscriptions:

If you haven’t set up the next season start date while defining a seasonal schedule (a group of seasons) that is linked to your seasonal subscription offer, the next payment date will not be set. As a result, /customers/{customerId}/subscriptions endpoint will return 2145913200 as expiresAt.

To avoid displaying this date, make sure to provide an appropriate text that will appear instead, for example: “Next payment is at the beginning of the new season” or “Renews automatically on the next season start”.

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.

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.

Subscription switch

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

🚧

Important - Supported payment gateways

Subscription switch (upgrade and downgrade) feature requires compatibility of the payment connector and payment gateway. Currently the feature is fully supported for the following: Adyen, PayPal.

Please contact Cleeng Broadcaster Support Team if you wish to use other payment connectors/gateways.

Prerequisites

Proper configuration is required in the Dashboard for the subscription switches to work.

1. Offer switch settings (optional) - they provide different settings (algorithms) affecting such aspects as entitlements (whether a customer gets access to a new plan immediately or not), billing cycle (whether it changes with subscription switch), refund behavior, or time proration as well as let you decide on free trial behavior.

   You can use default values or select others that better suit your needs, and then you have to set them up in the Dashboard. For more information, see the Supported subscription switch algorithms article.

🚧

Important

Please remember to subscribe to capturePayment webhook if you decide to use subscription switch algorithms with charge, such as:

• Immediate and charge with full refund
• Immediate and charge without proration
• Immediate and charge with time proration
• Immediate and charge with refund

Please remember to subscribe to refundPayment webhook if you decide to use subscription switch algorithms with refund, such as:

• Immediate and charge with refund
• Immediate and charge with full refund

2. Offer switching configuration (required) - a Broadcaster has to define possible upgrades and downgrades for a given offer in subscription switch settings in the dashboard. The hierarchy should be clearly defined: which plan can be upgraded or downgraded to which one.

   For a detailed guide, see the Subscription upgrades and downgrades article.

Step-by-Step Guide

📘

Important

• If you're using MediaStore SDK components, you can see the example look and feel here.
• 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 section.

Follow the steps below to change a subscription plan:

Step 1: List Possible Switch Options

Call this endpoint: /customers/:customerId/subscription_switches/:offerId/availability to display "change plan" options to a customer.

🚧

Please 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.

Step 2: Select and Request a Switch

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

Subscription switch is an asynchronous process and it may take a while. The switch will happen as per your switch settings.

Two basic kinds of switch are possible when it comes to access to content: immediate and deferred.

Immediate switch

The switch may be immediate - when the switch settings allow the customer to get access to the new plan instantly.
In such a situation when the customer confirms the change to another plan, he/she will see the new plan after returning to plan details.

Deferred switch

If the subscription switch is deferred - the subscription plan and access rights change when the subscription renews. Then a customer may still change his/her mind before the actual switch takes place.

In such a situation when the customer confirms the change to another plan, he/she will see the new plan after returning to plan details, but there should be a Stop switch button available as the switch is pending.

Pending switch

“Pending” is the status of the subscription switch (upgrade or downgrade) that represents a customer’s will to change his/her subscription plan. It is the status between the subscription switch request and the actual switch processing.
It is a special status, because the customer can still manage the switch (for other available switch statuses see below).

API endpoints are provided for fetching details about switches and managing them.

Detecting a pending switch

Information about a pending switch is present in the following endpoints:

• Fetch customer's subscriptions
• Fetch customer's offers

Their responses include the pendingSwitchId parameter if they have a pending switch.

Managing pending switches

You can change a switch only if it is not being processed yet (when payment authorization has not been made yet).

You can manage a pending upgrade or downgrade using this endpoint:

• Update switch

Currently it supports the cancelled status so you can only cancel a pending switch.

Information about switches

You can fetch detailed information about switches with the following endpoints:

• List switches
• Fetch switch details

Statuses of switches

The following switch statuses are supported:

• pending - the status of a switch that represents a customer’s will to change his/her subscription plan. It is the status between the subscription switch request and the actual switch processing. While a switch is in pending status, a customer can still cancel it.

• inprogress - the status when a switch is being processed (e.g. payment processing has started). This status applies to switches that require charge.

• cancelled - the status of a switch that has been cancelled by a customer. A switch can be cancelled only while its status is pending.

• finished - the status of a switch that was processed successfully and is complete. The customer has access to a new subscription plan.

• failed - the status of a switch that was unsuccessful (e.g. payment failed). The customer does not have access to a new subscription plan.

📘

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).