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.
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:
- Listen to the Instance App Installed
webhook. Make sure to save the
data.instanceId
from the payload. - Pass the
instanceID
when calling Get App Instance. - 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. - 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 thatinstance.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, theownerInfo
object is always returned empty. - 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:
- Listen to the Instance App Installed
webhook. Make sure to save the
data.instanceId
from the payload. - Pass the
instanceID
when calling Get App Instance to retrieve installed Wix apps. You can find them as human-readable names in thesite.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. - 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:
- Listen to the Instance App Installed
webhook. Make sure to save the
data.instanceId
from the payload. - Pass the
instanceID
when calling Get App Instance to retrieve the site owner's email, you can find it ininstance.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, theownerInfo
object is always returned empty. - Set up the automatic user login on your app's side.
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.
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.
App name, as set by you in the Wix Developers Center during the app creation process.
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.
Whether the site owners have installed a free or paid version of your app on their site.
Billing information for the app instance. Available only in case {"isFree": false}.
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.
Plans available to this app instance.
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.
Deprecated. This parameter will be removed on March 30, 2023. Use copiedFromTemplate instead.
Whether the app instance was created when another Wix site was cloned.
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:Triggered when an instance of your app is installed on a Wix site.
Unique identifier of the app within the website.
Instance ID of the app in the original website (relevant only when this site was duplicated from another site).
Triggered when an instance of your app is uninstalled from a Wix site.
Unique identifier of the app within the website.
Triggered when a site owner purchases a paid plan for your app.
Date and time of purchase.
Purchased app plan.
Selected payment cycle.
Plan expiration date.
Coupon applied to purchase (if relevant).
Invoice ID.
Triggered when a site owner upgrades or downgrades their plan for your app.
Date and time of change.
Newly purchased app plan.
Newly selected payment cycle.
Previous app plan.
Previous payment cycle.
Coupon applied to purchase (if relevant).
Invoice ID.
Triggered when a site owner cancels a paid plan for your app. The site owner can continue to use your app until the end of the current billing cycle.
Date and time of auto-renewal cancellation.
Current app plan.
Current payment cycle.
Supported values: UNKNOWN_CANCELLATION_TYPE_ERROR_STATE, USER_CANCEL, FAILED_PAYMENT, TRANSFER_CANCELLATION_REASON. Reason provided by app for cancellation (if relevant).
Reason provided by site owner for cancellation (if relevant).
Cancellation type.