Recurring Plans

Overview

Every app can have one or three different recurring premium plans, plus a free version. To support premium features in your app, you’ll need to first check the user’s plan so that you can activate the right features.  

Check out our pricing guide to learn more about premium plans and how to price your app.
How does it work?

When we access your app’s endpoint, we pass along a set of query parameters that describes the app’s context.

The app’s premium status is displayed in the vendorProductId property in the app instance query parameter.  

Before you start

When you add your app details in the Dev Center, define a “Package ID” for each premium plan.

You’ll use this package ID to identify the user’s premium status: if your package ID is displayed in the vendorProductId property, you’ll know that the user upgraded your app.

Activate the right plan

You’ll activate or block specific features, depending on the value of vendorProductId (in the app instance query parameter):

  1. If the value matches the Package ID you defined in the Dev Center – this app is premium, so activate your premium features (if you have more than one premium plan, the value indicates the specific premium plan).
  2. If the value is “null” – this app is free, so activate your app’s free features only.

Example of a decoded instance parameter:

How to downgrade users

Users can cancel their premium plan at any time. However, don’t downgrade the user until the subscription ends – at the end of the month or year, depending on your app’s payment plan. During this time, the user will have a premium app and the instance will include the package ID in the vendorProductId property.

Once the premium package expires, we’ll change the value of vendorProductId property to “null” – that’s when you should activate the app’s free plan.

Upgrade Button

Wherever you have an upgrade button/link in your app, use the SDK to open the billing page directly from your app:  

Only have one premium plan? Once the user upgrades, make sure you hide the upgrade button.

Where should you add the Upgrade button in your app? Learn more about the design guidelines for the App Settings panel and the Dashboard component.
Offer a trial period

As we mentioned in our pricing guidelines: if you don’t include a free plan for your app, we highly recommend that you offer users a trial period.

You manage the trial period, which means that you are responsible for keeping track of the trial days for each user. Once the trial period is over, you can lock the app and ask the user to upgrade.

Here’s how it works:

  1. During the trial period, your app should work just like a free app. This means that the app instance query parameter won’t hold the Package ID, but the user’s site will display a premium app.
  2. Let users know how many days are left in the trial. Display a message in your App Settings panel to let the user know how many days are left in the trial – follow this PSD.
  3. Once the trial is over, notify the user and lock the app. Follow the guidelines in this PSD.
    • In the App Settings panel: lock the app and ask the user to upgrade.
      -Change the CTA button in the Main tab to be an upgrade button with class btn-upgrade.
      -Display a notification next to the Main label. When users hover over it, display a tooltip. (Use the showTabNotification function in the panel tabs UI control.)
    • In the Editor: display a notification inside your site component to let the user know that the trial expired.
    • In the live site (and preview): talk to your account manager to decide whether or not your app should disappear from the user’s live site. If your app should still appear on the site, lock the app and display a notification for site visitors.
  4. If the user upgrades the app, unlock the premium features. Once the user upgrades, the Package ID will appear in the app instance query parameter of your endpoint’s URL, and you will know that the user has upgraded to premium.

Was this page helpful?

What can we do to improve it?

What did you like about it?