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

Object

json

1
2{
3 "instance": {
4 "appName": "MY_SHINY_APP",
5 "appVersion": "0.0.53",
6 "billing": {
7 "billingCycle": "MONTHLY",
8 "packageName": "e8f429d4-0a6a-468f-8044-87f519a53202"
9 },
10 "instanceId": "07864c16-3a6f-4dd2-9973-028705762b2c",
11 "isFree": false,
12 "permissions": [
13 "WIX_DEVELOPERS.CREATE_CHECKOUT",
14 "WIX_DEVELOPERS.MANAGE_APP_INSTANCE",
15 "WIX_DEVELOPERS.MANAGE_CHARGE"
16 ]
17 },
18 "site": {
19 "locale": "he",
20 "multilingual": {
21 "isMultiLingual": false,
22 "supportedLanguages": []
23 },
24 "paymentCurrency": "ILS",
25 "siteDisplayName": "Mysite 34",
26 "url": "https://doereg11.wixsite.com/mysite-34",
27 "description": "My awesome site is all about selling stuff"
28 }
29}

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://www.wixapis.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

Request

curl

Copy Code
1curl -X GET \
2 https://www.wixapis.com/api/v1/instance \
3 -H 'Authorization: <AUTH>'

Response

json

1
2{
3 "instance": {
4 "appName": "MY_SHINY_APP",
5 "appVersion": "0.0.53",
6 "billing": {
7 "billingCycle": "MONTHLY",
8 "packageName": "e8f429d4-0a6a-468f-8044-87f519a53202"
9 },
10 "instanceId": "07864c16-3a6f-4dd2-9973-028705762b2c",
11 "isFree": false,
12 "permissions": [
13 "WIX_DEVELOPERS.CREATE_CHECKOUT",
14 "WIX_DEVELOPERS.MANAGE_APP_INSTANCE",
15 "WIX_DEVELOPERS.MANAGE_CHARGE"
16 ]
17 },
18 "site": {
19 "locale": "he",
20 "multilingual": {
21 "isMultiLingual": false,
22 "supportedLanguages": []
23 },
24 "paymentCurrency": "ILS",
25 "siteDisplayName": "Mysite 34",
26 "url": "https://doereg11.wixsite.com/mysite-34",
27 "description": "My awesome site is all about selling stuff"
28 }
29}

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

1{
2 "data": {
3 "eventType": "<event-type>",
4 "instanceId": "<app-instance-id>",
5 "data": "<stringified-JSON>"
6 }
7}

The parsed data will include:

Sample Data

1
2{
3 "data": {"appId": "5bc2062d-010b-448c-a62a-d6bb269c5a4c"},
4 "instanceId": "3bbcabc7-ebb7-4fc8-8829-13ea0e142123",
5 "eventType": "AppInstalled"
6}

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

1{
2 "data": {
3 "eventType": "<event-type>",
4 "instanceId": "<app-instance-id>",
5 "data": "<stringified-JSON>"
6 }
7}

The parsed data will include:

Sample Data

1
2{
3 "data": {"appId": "5bc2068d-010b-448c-a62a-d6bb269c5a4c"},
4 "instanceId": "8e9d6b70-6eb9-4ab3-a62d-e033063e2f05",
5 "eventType": "AppRemoved"
6}

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

1{
2 "data": {
3 "eventType": "<event-type>",
4 "instanceId": "<app-instance-id>",
5 "data": "<stringified-JSON>"
6 }
7}

The parsed data will include:

Sample Data

1
2{
3 "data": {
4 "operationTimeStamp": "2019-12-09T07:55:18.356Z",
5 "vendorProductId": "e8f429d4-0a6a-468f-8044-87f519a53202",
6 "cycle": "MONTHLY",
7 "cancelReason": "USER_CANCEL",
8 "userReason": "Cancel reason: No reason chosen",
9 "subscriptionCancellationType": "AT_END_OF_PERIOD"
10 },
11 "instanceId": "8e9d6b70-6eb9-4ab3-a62d-e033063e2f05",
12 "eventType": "PaidPlanAutoRenewalCancelled"
13}

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

1{
2 "data": {
3 "eventType": "<event-type>",
4 "instanceId": "<app-instance-id>",
5 "data": "<stringified-JSON>"
6 }
7}

The parsed data will include:

Sample Data

1
2{
3 "data": {
4 "operationTimeStamp": "2019-12-08T07:42:04.535Z",
5 "vendorProductId": "e61158e5-e327-4694-ac50-2a3a0db87c84",
6 "cycle": "YEARLY",
7 "previousVendorProductId": "e61158e5-e327-4694-ac50-2a3a0db87c84",
8 "previousCycle": "MONTHLY"
9 },
10 "instanceId": "5bc2068d-010b-448c-a62a-d6bb269c2a4c",
11 "eventType": "PaidPlanChanged"
12}

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

1{
2 "data": {
3 "eventType": "<event-type>",
4 "instanceId": "<app-instance-id>",
5 "data": "<stringified-JSON>"
6 }
7}

The parsed data will include:

Sample Data

1
2{
3 "data": {
4 "operationTimeStamp": "2019-12-09T07:44:53.659Z",
5 "vendorProductId": "e8f429d5-0a6a-468f-8044-87f519a53202",
6 "cycle": "MONTHLY",
7 "expiresOn": "2020-01-09T07:44:53Z"
8 },
9 "instanceId": "8e9d6b70-6eb9-4ab4-a62d-e033063e2f05",
10 "eventType": "PaidPlanPurchased"
11}

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)

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://www.wixapis.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

Request

curl

Copy Code
1curl -X POST \
2 https://www.wixapis.com/api/v1/scripts \
3 -H 'Authorization: <AUTH>' \
4 -d '{
5 "properties": {
6 "parameters": {
7 "MY_DYNAMIC_PARAMETER": "HB-23466-35"
8 }
9 }
10 }'

Response

json

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

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://www.wixapis.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

Request

curl

Copy Code
1curl -X GET \
2 https://www.wixapis.com/api/v1/scripts \
3 -H 'Authorization: <AUTH>'

Response

json

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

Billing

Get Url

Gets a dynamic checkout URL based on the parameters passed in the request

Permissions

The API requires WIX_DEVELOPERS.CREATE_CHECKOUT permission

POST

https://www.wixapis.com/api/v1/checkout

Request Headers

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

Body Params

NAME
TYPE
DESCRIPTION

testCheckout

boolean

Whether this checkout is for testing purposes only (when true, the price charged will be 0.00)

billingCycle

string

One of NONE_CYCLE, MONTHLY, YEARLY.

Billing cycle (MONTHLY/YEARLY)

languageCode

string

Optional - ISO-639-1: defaults to "en"

countryCode

string

Optional - ISO-3166-1 alpha-2: defaults to "US"

successUrl

string

URL to redirect the user to after a successful purchase

productId

string

Product to bill the user for (details will be taken from dev-center)

Status/Error Codes

The response will include an HTTP status code.

Response Object

NAME
TYPE
DESCRIPTION

checkoutUrl

string

Wix checkout URL based on the parameters in the request

Example of Get Url request

Request

curl

Copy Code
1curl -X POST \
2 https://www.wixapis.com/apps/v1/checkout \
3 -H 'Authorization: <AUTH>' \
4 -H 'Content-Type: application/json' \
5 -d '{
6 "productId": "e8f429d4-0a6a-468f-8044-87f519a53202",
7 "billingCycle": "MONTHLY"
8 }'

Response

json

1
2{"checkoutUrl": "https://www.wix.com/apps/upgrade/order-checkout?token=JWS.eyJraWQiOiJaUnliMG5pbCIsImFsZyI6IkhTMjU2In0.eyJkYXRhIjoie1wib3JkZXJJdGVtc1wiOlt7XCJwcm9kdWN0SWRdIjpcImIwZjgwOGMzLWM4YmUtNGNkYS1iNmQyLTc0YTExNTM2ZDdiZFwiLFwicXVhbnRpdHlcIjoxLFwicGF5bWVudEN5Y2xlXCI6XCJNT05USExZXCIsXCJkaXNwbGF5TmFtZVwiOlwiXCIsXCJjb3Vwb25Db2RlXCI6bnVsbCxcImJpbGxpbmdTZXJ2aWNlSWRcIjpudWxsLFwib3ZlcnJpZGVQcmljZVwiOlwiOC4wXCIsXCJleHRlcm5hbE9yZGVySXRlbUlkXCI6XCJMaW5lSXRlbV8wXCJ9XSxcInN1Y2Nlc3NVcmxcIjpcImh0dHBzOi8vd3d3LndpeC5jb20vYXBwcy91cGdyYWRlL29yZGVyLXJlc3VsdFwiLFwid2l4VXNlckd1aWRcIjpudWxsLFwidXNlckVtYWlsXCI6bnVsbCxcImxhbmd1YWdlQ29kZVwiOlwiZW5cIixcImN1cnJlbmN5Q29kZVwiOlwiVVNEXCIsXCJvcmRlclBhcmFtc1wiOntcInNpdGVHdWlkXCI6XCIxMTE0MjExNC0yZDExLTRkNzYtOWEzZS0zZjUzMzBiNjBhYzdcIn0sXCJldmVudEFnZ3JlZ2F0b3JcIjpcImYzNGY1MGE4LTc3ZDMtNDE1Ny1iM2Q3LTZiMDJkYzI2ODQ1NlwiLFwiaW5pdGlhdG9yXCI6XCJBcHAgTWFya2V0IFRQQSBBUElcIixcImNvdXBvbkRpc3BsYXlOYW1lXCI6bnVsbH0iLCJpYXQiOjE1NzQ1OTAyMDcsImV4cCI6MTU3NDc2MzAwN30.quYK2ND5tCTsaRPlQA5349ULQoWUwkdPzQEwcQhqc9s&appId=5bc2068d-010b-448c-a62a-d6bb269c5a4c&planId=e8f429d4-0a6a-468f-8044-87f519a53202"}