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.
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.
Triggered when an instance of your app is uninstalled from a Wix site.
Triggered when a site owner purchases a paid plan for your app.
Triggered when a site owner upgrades or downgrades their plan for your app.
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.