Search API library /

Generate a test token to explore our APIs

App Management

About App Management

Our App Management APIs provide your app with access to basic user data and app functionality.

Apps

App Instance

AppInstance Object

App instance data

Attributes

NAME

TYPE

DESCRIPTION

instanceId

string

App instance ID - a unique ID assigned to each app in each site

isFree

boolean

Returns true when the user has a free version of the app (and no package is found). Otherwise false

appName

string

App name

appVersion

string

App version installed at this instance

permissions

array<string>

Permissions included in this app's access token

billing

object

Billing info for this app in this site. Returns only if isFree is false

Example of AppInstance

json

{
"instanceId": "877477af-95ff-40a2-a0a6-e7262199fb15",
"appName": "LinkedIn B2B Ads",
"appVersion": "0.0.16",
"isFree": false,
"billing": {
"packageName": "3f7a0486-93ad-4035-97b8-ad5dc01fb22c",
"billingCycle": "YEARLY"
},
"permissions": [
"WIX_DEVELOPERS.MANAGE_APP_INSTANCE",
"WIX_STORES.READ_PRODUCTS"
]
}

Get App Instance

Retrieves data about the installation of your app on the user's website

Permissions

The API requires WIX_DEVELOPERS.MANAGE_APP_INSTANCE permission

GET

https://dev.wix.com/api/v1/instance

Request Headers

This API requires an authentication header - pass the access token from the OAuth installation flow.

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME

TYPE

DESCRIPTION

instance

object

site

object

Example of Get App Instance request

curl

curl -X GET \
https://dev.wix.com/api/v1/instance \
-H 'Authorization: <AUTH>'

Response

json

{
"instance": {
"instanceId": "877477af-95ff-40a2-a0a6-e7262199fb15",
"appName": "LinkedIn B2B Ads",
"appVersion": "0.0.16",
"isFree": false,
"billing": {
"packageName": "3f7a0486-93ad-4035-97b8-ad5dc01fb22c",
"billingCycle": "YEARLY"
},
"permissions": [
"WIX_DEVELOPERS.MANAGE_APP_INSTANCE",
"WIX_STORES.READ_PRODUCTS"
]
},
"site": {
"siteDisplayName": "mysite-22",
"locale": "en",
"paymentCurrency": "ILS",
"multilingual": {
"isMultiLingual": false,
"supportedLanguages": []
}
}
}

App Installed Webhook

When you sign up for the App Installed webhook, you will receive this notification when your app is installed on a site

Event Body

The event's data is received as a JSON Web Token (JWT). Make sure to verify that the data was received by Wix - read more about it in the Webhooks article.

Payload

NAME

TYPE

DESCRIPTION

appId

string

The data payload will include the following as an encoded JWT:

Event Body

json

{
"data": {
"eventType": "<event-type>",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>"
}
}

The parsed data will include:

Sample Data

{
"appId": "768d2905-7b81-4cba-aa2c-2183f364ba1e",
}

App Removed Webhook

When you sign up for the App Removed webhook, you will receive this notification when your app is uninstalled from a site

Event Body

The event's data is received as a JSON Web Token (JWT). Make sure to verify that the data was received by Wix - read more about it in the Webhooks article.

Payload

NAME

TYPE

DESCRIPTION

appId

string

The data payload will include the following as an encoded JWT:

Event Body

json

{
"data": {
"eventType": "<event-type>",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>"
}
}

The parsed data will include:

Sample Data

{
"appId": "768d2905-7b81-4cba-aa2c-2183f364ba1e",
}

Paid Plan Purchased Webhook

When you sign up for the Paid Plan Purchased webhook, you will receive this notification when a site owner purchases a paid plan

Event Body

The event's data is received as a JSON Web Token (JWT). Make sure to verify that the data was received by Wix - read more about it in the Webhooks article.

Payload

NAME

TYPE

DESCRIPTION

vendorProductId

string

operationTimeStamp

string

couponName

string

expiresOn

string

cycle

string

One of NONE_CYCLE, MONTHLY, YEARLY.

The data payload will include the following as an encoded JWT:

Event Body

json

{
"data": {
"eventType": "<event-type>",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>"
}
}

The parsed data will include:

Sample Data

{
"vendorProductId": "2a7518dd-bd2d-46b2-ac37-155ed61ac31a",
"instanceId": "e23cd636-dab1-4c75-9490-918cfe8b1f03"
"couponName": "abcFLORaDMK2017"
}

Paid Plan Changed Webhook

When you sign up for the Paid Plan Changed webhook, you will receive this notification when a user changes the app’s paid plan (to another paid plan)

Event Body

The event's data is received as a JSON Web Token (JWT). Make sure to verify that the data was received by Wix - read more about it in the Webhooks article.

Payload

NAME

TYPE

DESCRIPTION

vendorProductId

string

operationTimeStamp

string

previousCycle

string

One of NONE_CYCLE, MONTHLY, YEARLY.

previousVendorProductId

string

couponName

string

cycle

string

One of NONE_CYCLE, MONTHLY, YEARLY.

The data payload will include the following as an encoded JWT:

Event Body

json

{
"data": {
"eventType": "<event-type>",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>"
}
}

The parsed data will include:

Sample Data

{
"previousVendorProductId": "2a7518dd-bd2d-46b2-ac37-155ed61ac31a",
"previousCycle": "YEARLY"
"couponName": "abcFLORaDMK2017"
"instanceId": "e23cd636-dab1-4c75-9490-918cfe8b1f03"
}

Paid Plan Auto Renewal Cancelled Webhook

When you sign up for the Paid Plan Auto-Renewal Cancelled webhook, you will receive this notification when a user cancels their paid plan. (The user will remain a paying user until the plan expires)

Event Body

The event's data is received as a JSON Web Token (JWT). Make sure to verify that the data was received by Wix - read more about it in the Webhooks article.

Payload

NAME

TYPE

DESCRIPTION

vendorProductId

string

operationTimeStamp

string

cancelReason

string

cycle

string

One of NONE_CYCLE, MONTHLY, YEARLY.

userReason

string

subscriptionCancellationType

string

The data payload will include the following as an encoded JWT:

Event Body

json

{
"data": {
"eventType": "<event-type>",
"instanceId": "<app-instance-id>",
"data": "<stringified-JSON>"
}
}

The parsed data will include:

Sample Data

{
"vendorProductId": "3f7a0486-93ad-4035-97b8-ad5dc01fb22c",
"cycle": "YEARLY"
"cancelReason": "USER_CANCEL"
"userReason": "Cancel reason: App is too expensive"
"subscriptionCancellationType": "AT_END_OF_PERIOD"
"instanceId": "e23cd636-dab1-4c75-9490-918cfe8b1f03"
}

Embedded Scripts

ScriptProperties Object

Embedded script data

Attributes

NAME

TYPE

DESCRIPTION

parameters

object

Script parameters Map

disabled

boolean

Whether script is disabled or not, defaults to false (not disabled)

Get Embedded Script

Retrieves this app's existing embedded script parameters

If the app does not have an embed on the site, this endpoint will return 404

Permissions

The API requires APPS.MANAGE_EMBEDDED_SCRIPT permission

GET

https://dev.wix.com/api/v1/scripts

Request Headers

This API requires an authentication header - pass the access token from the OAuth installation flow.

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME

TYPE

DESCRIPTION

properties

object

Script instance on this website

Example of Get Embedded Script request

curl

curl -X GET \
https://dev.wix.com/api/v1/scripts \
-H 'Authorization: <AUTH>'

Response

json

{
"properties": {
"parameters": {
"MY_DYNAMIC_PARAMETER": "HB-23461-35"
}
}
}

Embed Script

Inject a script in an app with an existing embedded script component, with the given parameters

Permissions

The API requires APPS.MANAGE_EMBEDDED_SCRIPT permission

POST

https://dev.wix.com/api/v1/scripts

Request Headers

This API requires an authentication header - pass the access token from the OAuth installation flow.

Body Params

NAME

TYPE

DESCRIPTION

properties

object

Parameters to embed

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME

TYPE

DESCRIPTION

properties

object

Script instance on this website

Example of Embed Script request

curl

curl -X POST \
https://dev.wix.com/api/v1/scripts \
-H 'Authorization: <AUTH>' \
-d '{
"properties": {
"parameters": {
"MY_DYNAMIC_PARAMETER": "HB-23466-35"
}
}
}'

Response

json

{
"properties": {
"parameters": {
"MY_DYNAMIC_PARAMETER": "HB-23461-35"
}
}
}