> Portal Navigation:
>
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt
## Resource: Adjust a Blocks App to Different Pricing Plans
## Article: Adjusting Your Blocks App to Different Pricing Plans
## Article Link: https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/publish-blocks-apps-to-the-app-market/adjust-a-blocks-app-to-different-pricing-plans.md
## Article Content:
# Adjust a Blocks App to Different Pricing Plans
**Editor compatibility**
Wix Blocks apps aren't supported in the Wix Harmony editor. Existing Blocks apps remain available for purchase on the Wix App Market for Wix Editor and Wix Studio sites. To learn more, see [About Wix Harmony and Blocks](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/about-wix-harmony-and-blocks.md).
When you [publish your Blocks app in the Wix App Market](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/publish-blocks-apps-to-the-app-market/publish-a-blocks-app-to-the-app-market.md), you can choose to provide different app behaviors for different pricing plans. For example, users who use a free version of your app may get several services, while those who pay for it, get more. This requires creating and managing a system that identifies the user, determines their pricing plan and impacts the app's behavior.
This is an example of how users see your pricing page:
## What you need to adjust in Blocks
Before you begin adjusting your app to different pricing plans, make sure to [define your business model](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/about-pricing-plans-and-business-models.md) in your app dashboard. This is the first and essential step.
Now, you need to adjust your app to handle these pricing plans with your own user interface and code. This includes:
* Creating a different UI for each plan
* Adding code to handle each plan
Also, optionally:
* Configuration adjustments
* Customizing panels
* Installation settings
Notes:
* For each plan, you can also add a [free trial](https://dev.wix.com/docs/build-apps/launch-your-app/pricing-and-billing/set-up-and-manage-free-trials.md).
* If you want to add in-app purchases (also known as one-time payments), you must add a dashboard page and add [OAuth](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/about-oauth.md).
* If you already published your app, and now you want to test the app with your pricing plans, create a [test coupon](https://dev.wix.com/docs/build-apps/launch-your-app/app-promotion/self-promotion/create-a-coupon.md).
Example:
Here is an [example Blocks app](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/publish-blocks-apps-to-the-app-market/example-app-with-pricing.md) that uses pricing plans.
## Step 1 | Create a UI for the different plans
Since your app needs to behave differently to users according to their different pricing plans, the first thing you should understand is what the different users see. You can do this through a [multi-state box](https://dev.wix.com/docs/develop-websites/articles/wix-editor-elements/other-elements/multi-state-boxes/about-multi-state-boxes.md), which gives you different user interface with no code at all. Alternatively, you can delete and restore elements with the [`delete()`](https://www.wix.com/velo/reference/$w/panelthumbnails/delete?utm_source=google&utm_medium=cpc&utm_campaign=13708482663%5E124757113632&experiment_id=%5E%5E530755701296%5E%5E_DSA&gclid=CjwKCAjw8symBhAqEiwAaTA__Opbaej4Mz91N_ANHXR3YdIfGvVBLK50mPCvguckVBrKOJfVxE5FBRoCbekQAvD_BwE) and [`restore()`](https://www.wix.com/velo/reference/$w/panelthumbnails/restore?utm_source=google&utm_medium=cpc&utm_campaign=13708482663%5E124757113632&experiment_id=%5E%5E530755701296%5E%5E_DSA&gclid=CjwKCAjw8symBhAqEiwAaTA__Opbaej4Mz91N_ANHXR3YdIfGvVBLK50mPCvguckVBrKOJfVxE5FBRoCbekQAvD_BwE) methods.
**Should I use a multi-state box or delete() and restore() ?**
* If you want a completely different behavior in the different plans, it's best to choose a **multi-state box**.
* If most of the behavior is similar, and you want to modify just several specific elements - use **delete()** and **restore()**.
## Step 2 | Code
When your Blocks app is installed on a site, it generates a JSON Web Token (JWT) for that app instance. You can find information about the app's pricing in the `billing` field of the [app instance](https://dev.wix.com/docs/sdk/backend-modules/app-management/app-instances/sample-flows.md). The `billing` field is available only if the `isFree` value is false. Get the app instance in a backend file and then call it from the frontend.
Note:
To get the app instance from **panel or dashboard code**, use the Velo `getDecodedAppInstance` function and not the SDK `getAppInstance`.
### Backend
Add this code to a `web.js` file:
```js
import { webMethod, Permissions } from "@wix/web-methods";
import { auth } from "@wix/essentials";
import { appInstances } from "@wix/app-management";
export const getInstance = webMethod(Permissions.Anyone, async () => {
try {
const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance);
const response = await elevatedGetAppInstance();
return response;
// Information about the billing is in the billing object of the GetAppInstanceResponse object.
} catch {
console.log("error");
}
})
```
### Frontend
Import the function in your frontend code:
```js
import { getInstance } from "backend/instance.web";
$w.onReady(function () {
// Initialize pricing plan data
loadPricingPlan();
});
async function loadPricingPlan() {
try {
// Get instance data from backend
const response = await getInstance();
// Check if app has billing (paid app)
if (response?.instance?.billing?.packageName) {
const pricingPlan = response.instance.billing.packageName;
console.log("Paid plan: ", pricingPlan);
} else {
console.log("Free app - no billing information");
}
} catch (error) {
// Display console level error handling
console.error("Error loading pricing plan:", error);
}
}
```
See deprecated wix-application code example
Use `wix-application` if you need to get the pricing plan in the frontend:
```javascript
import wixApplication from 'wix-application';
$w.onReady(async function () {
instance = await wixApplication.getDecodedAppInstance();
plan = instance.vendorProductId;
//You configured vendorProductId in the app dashboard.
//If there is no plan, the value is null.
// Now, add your logic for the different plans
});
$widget.onPropsChanged((oldProps, newProps) => {
});
```
Use `wix-application-backend` if you need to get the pricing plan in a backend file:
```js
import * as wixApplicationBackend from 'wix-application-backend';
export async function getInstance() {
return wixApplicationBackend.getDecodedAppInstance();
}
```
## Step 3 | Handle plan cancellation
Your app logic should also handle the case where users canceled the plan after they upgraded. When handling this, think about the site builder _and_ the site visitor who is the end user of their app.
### If plan is canceled: site builder experience
If users cancel their plan at any point, you'll want to stop the app or some of its features from working. In this case:
* Display a notification in a central, visible place in the app, and prevent the app (or premium features) from working. Note the difference between a premium app, which does not work at all unless it's paid for, and a freemium app, where you should block only the premium features.
* Provide [entry points to upgrade](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/publish-blocks-apps-to-the-app-market/provide-entry-points-to-upgrade-your-app.md) your app. This can be done in the widget's action bar, settings panel, or in the app Dashboard.
### If plan is canceled: site visitor experience
Your direct user is the site builder who installed your app. However, you should also think about the user of your user, the site visitor.
If users cancel their plan at any point, lock the app (or its premium features) from working. If it's a premium only app, we recommend to collapse (delete) it, so it's not seen on the site. If you can't collapse it, present an indication, such as: "This app / feature is currently unavailable, contact the Wix user for details". This is also true for dashboard apps - collapse the app or present a proper message.
Note:
To get the app instance from **panel or dashboard code**, use the Velo `getDecodedAppInstance` function and not the SDK `getAppInstance`.
Here is a code example for collapsing the widget after the cancellation:
### Backend
Add this code to a `web.js` file:
```ts
import { webMethod, Permissions } from "@wix/web-methods";
import { auth } from "@wix/essentials";
import { appInstances } from "@wix/app-management";
export const getInstance = webMethod(Permissions.Anyone, async () => {
try {
const elevatedGetAppInstance = auth.elevate(appInstances.getAppInstance);
const response = await elevatedGetAppInstance();
return response;
} catch {
console.log("error");
}
})
```
### Frontend
Import the function in your frontend code:
```ts
import { getInstance } from "backend/instance.web";
$w.onReady(function () {
// Initialize widget visibility based on app plan
isPlanCanceled();
});
// General functions
async function isPlanCanceled() {
try {
// Get instance data from backend
const response = await getInstance();
// Check if app is on free plan - use optional chaining for safety
const isAppFree = response?.instance?.isFree;
if (isAppFree) {
// Remove the widget's container from the stage for free apps
$w("#widgetContainer").delete();
}
} catch (error) {
// Display console level error handling
console.error("Error checking app plan:", error);
}
}
```
See deprecated wix-application code example
```javascript
import wixApplication from 'wix-application';
let plan, instance;
$w.onReady(async function () {
instance = await wixApplication.getDecodedAppInstance();
plan = instance.vendorProductId;
if (plan == null) {
$w('#box1').delete(); //remove the widget's container from the stage
}
});
```
## Step 4 | Configuration
Now, you might want to make some changes in the **Configuration** tab in Blocks.
You can define certain elements of your widget, such as a flexbox that helped you layout the elements, as non-selectable. You can also change display names. Make sure to think about all your pricing plans when making these changes.
Learn more about [configuring widget and element display names and behavior](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/editor-experience-configuration/configure-display-names-and-behavior-in-blocks.md).
Once you define a pricing plan for your app, your widget automatically gets an Upgrade button in its action bar. Learn more about [configuring action bars](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/editor-experience-configuration/configure-action-bars-in-blocks.md)
## Step 5 | Customize your panels
You can show or hide panel elements according to the app's billing, just as you did in the widget code. This is done in the [code section](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/editor-experience-panels/add-code-to-custom-panels-in-blocks.md) of your panel in the **Panels** tab.
You can also add a button or link in your panel to upgrade your app. Learn more about [entry points to upgrade your app](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/publish-blocks-apps-to-the-app-market/provide-entry-points-to-upgrade-your-app.md).
## Step 6 | App and widget installation settings
Your app installation settings allow you to control what widgets are seen in a site's Add Elements panel, and more options. Make sure to think about all your pricing plans when you go over your installation settings.
Learn more about [app and widget installation settings](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-blocks/deploy-and-manage-blocks-apps/configure-blocks-installation-settings.md).