About the App Instances API

The App Instances API allows to track on which Wix sites your app is installed and when a subscription for your app is modified.

With the App Instances API, you can:

  • Get notified by Wix when a site owner installs your app on their site.
  • Track data that's associated with individual app instances.
  • Receive notifications from Wix when site owners modify or cancel their subscription for your app.

See the Billing API for more information how to charge site owners for using your app.

Before you begin

It’s important to note the following points before starting to code:

  • Site owners can install only a single version of your app on their site. For example, they can't install a free and paid version of your app at the same time.

Use cases

Terminology

  • App instance: Specific occurrence of your app on a particular Wix site.
  • Paid plan: The site owners have installed a version of your app that isn't free of charge. Your app could charge them a single one-time payment or on a subscription basis.
Was this helpful?
Yes
No

App Management: Sample Use Cases and Flows

This article shares some possible use cases your app could support, as well as a sample flow that could support each use case. This can be a helpful jumping off point as you plan your app's implementation.

Reach out to new users

You could reach out to your app's new users. For example, you could encourage free users to upgrade their version.

To reach out to new users:

  1. Listen to the Instance App Installed webhook. Make sure to save the data.instanceId from the payload.
  2. Pass the instanceID when calling Get App Instance.
  3. Optional: In the response data, confirm that the site owner's have installed the free version of your app by checking instance.isFree. You may use this information to encourage them to upgrade.
  4. Save the site owner's email, you can find it in instance.ownerInfo.email. Make sure to confirm that the user has opted in to receive communication by checking that instance.ownerInfo.emailStatus is either "VERIFIED_OPT_IN" or "NOT_VERIFIED_OPT_IN". Note that you must have added the Read Site Owner Email permission scope to your app during the setup process in the Wix Developers Center. In case you, haven't requested this permission, the ownerInfo object is always returned empty.
  5. Optional: In case the owner's have opted in to receive notifications, send them an email that includes a link to the Upgrade Button. Then, you could listen to the Paid Plan Purchased webhook to get notified about the upgrade.

We recommend signing up for the Instance App Installed webhook. In case your app is using Wix REST APIs, you would also receive an access token that includes the app instance ID during the OAuth setup, but listening to the webhook ensures the installation process has succeeded.

Identify a site's installed Wix business solutions

In case your app requires that the site owners have also installed a specific Wix business solution, you can verify that the relevant app is installed on that site. During your app's setup process in the Developers Center you can mark one or more Wix app's as requirements, but we recommend to follow this flow since you may support different use cases, depending on which Wix app is installed. For example, your app may support different use cases, depending on whether the site includes Wix Stores or Wix Bookings.

To Identify a site's installed Wix apps:

  1. Listen to the Instance App Installed webhook. Make sure to save the data.instanceId from the payload.
  2. Pass the instanceID when calling Get App Instance to retrieve installed Wix apps. You can find them as human-readable names in the site.installedWixApps array. In case your app supports multiple use cases, check if you can identify the user's intent from the list of returned apps alone.
  3. If you can't identify the desired use case because the site owners have installed multiple Wix apps for which you support different flows, present a modal to them that lets them choose their preference.

Automatically log users in to your app

You could automatically create a user login for new customers of your app. Then, site owners don't need to set up an account for your app on their own. They could also share their account for your app with multiple contributors without being forced to share sensitive login info.

To create user logins:

  1. Listen to the Instance App Installed webhook. Make sure to save the data.instanceId from the payload.
  2. Pass the instanceID when calling Get App Instance to retrieve the site owner's email, you can find it in instance.ownerInfo.email. Note that you must have added the Read Site Owner Email permission scope to your app during the setup process in the Wix Developers Center. In case you, haven't requested this permission, the ownerInfo object is always returned empty.
  3. Set up the automatic user login on your app's side.
Was this helpful?
Yes
No
App Instance Object

An app instance is a specific occurrence of your app on a particular Wix site. When a site owner installs your app, a unique instance is generated for that specific site. Use the instanceId to keep track of the individual data associated with each app instance.

Properties
instanceIdstring
ID of the app instance. You can use it to keep track of the individual data that's associated with the specific occurence of your app that's installed on a Wix site.
appNamestring
App name, as set by you in the Wix Developers Center during the app creation process.
appVersionstring
Version of your app that's installed on the Wix site, as set by you in the Wix Developers Center during the app creation process.
isFreeboolean
Whether the site owners have installed a free or paid version of your app on their site.
billingobject
Billing information for the app instance. Available only in case {"isFree": false}.
permissionsArray <string>
List of permissions that the site owners have granted your app. You set the list of permissions that your app requires from the site owners in the Wix Developers Center during the app creation process.
availablePlansArray <AvailablePlan>
Plans available to this app instance.
originInstanceIdstring
ID of the Wix site from which the instance of your app has been cloned. Available only in case {"copiedFromTemplate": true}. All visual settings of the Wix site and app data are duplicated during the cloning process. Wix also notifies you in case there is any additional external functionality for the original site.
isOriginSiteTemplatebooleandeprecated
Deprecated. This parameter will be removed on March 30, 2023. Use copiedFromTemplate instead.
copiedFromTemplateboolean
Whether the app instance was created when another Wix site was cloned.
Was this helpful?
Yes
No
GetGet App Instance

Retrieves data about the instance of your app that's installed on the Wix site and the site itself.

You don't have to explicitly pass an identifier for the Wix site as part of the request, since this information is taken automatically from the context.

In case you want site.ownerInfo to be included in the response, you must have the Read Site Owner Email permission scope in addition to WIX_DEVELOPERS.MANAGE_APP_INSTANCE.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Your App
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/apps/v1/instance
Was this helpful?
Yes
No
Instance App Installed

Triggered when an instance of your app is installed on a Wix site.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
appIdstring
Unique identifier of the app within the website.
originInstanceIdstring
Instance ID of the app in the original website (relevant only when this site was duplicated from another site).
Was this helpful?
Yes
No
Instance App Removed

Triggered when an instance of your app is uninstalled from a Wix site.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
appIdstring
Unique identifier of the app within the website.
Was this helpful?
Yes
No