Search.../
  1. Home
  2. Getting Started
  3. Overview
Generate a test token to explore our APIs

About App Management

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

Was this helpful?

Apps

Instance related APIs Learn more.

Guides

Additional information about this section

App Instance
  • OBJECT
  • GET

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

  • WEBHOOK

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

  • WEBHOOK

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

  • 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)

  • WEBHOOK

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

Embedded Scripts
  • OBJECT

    Embedded script data

  • POST

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

  • GET

    Retrieves this app's existing embedded script parameters If the app does not have an embed on the site, this endpoint will return 404

Billing
  • POST

    The Wix Billing API enables your app to lead customers seamlessly into Wix's checkout process from your platform (e.g., hosting your app's pricing page ...

About This API

This API exposes basic data about the user's site and the app installed in it, as based on the user's authentication token.
When you provide the authentication token, you will receive identifying information for the user's site and the app instance parameters.
The primary identifier returned is the App Instance ID - the unique identifier of the app within the website. Using the App Instance ID, you can retrieve data about the site that installed the app (e.g., locale) and data about the app installed (e.g., current paid plan).

Was this helpful?

App Instance

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 paid plan 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

Was this helpful?

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

Authorization

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

Permissions

The API requires WIX_DEVELOPERS.MANAGE_APP_INSTANCE

GET

https://www.wixapis.com/apps/v1/instance

Request

This endpoint does not take any parameters

Response Object

Get App Instance Response

NAME
TYPE
DESCRIPTION
instance

object

site

object

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Get App Instance request

Request

curl

Copy Code
1curl -X GET \
2 https://www.wixapis.com/apps/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

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

Authorization

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

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

Was this helpful?

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

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

Authorization

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

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

Was this helpful?

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 Changed

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)

Authorization

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

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.

Was this helpful?

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

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

Authorization

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

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.

Was this helpful?

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}

Script Properties

Embedded script data

Attributes

NAME
TYPE
DESCRIPTION
parameters

object

Set of key-value pairs. Script parameters

disabled

boolean

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

Was this helpful?

Embed Script

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

Authorization

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

Permissions

The API requires APPS.MANAGE_EMBEDDED_SCRIPT

POST

https://www.wixapis.com/apps/v1/scripts

Body Params

NAME
TYPE
DESCRIPTION
properties

object

Parameters to embed

Response Object

Embed Script Response

NAME
TYPE
DESCRIPTION
properties

object

Script instance on this website

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Embed Script request

Request

curl

Copy Code
1curl -X POST \
2 https://www.wixapis.com/apps/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

Authorization

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

Permissions

The API requires APPS.MANAGE_EMBEDDED_SCRIPT

GET

https://www.wixapis.com/apps/v1/scripts

Request

This endpoint does not take any parameters

Response Object

Get Embedded Script Response

NAME
TYPE
DESCRIPTION
properties

object

Script instance on this website

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example of Get Embedded Script request

Request

curl

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

Response

json

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

Get Url

The Wix Billing API enables your app to lead customers seamlessly into Wix's checkout process from your platform (e.g., hosting your app's pricing page independently and redirecting to Wix checkout for purchase).
The checkout link is valid for 48 hours. Note: Use of this functionality is dependent on setup in the Wix Developers Center.

Authorization

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

Permissions

The API requires WIX_DEVELOPERS.CREATE_CHECKOUT

POST

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

Body Params

NAME
TYPE
DESCRIPTION
testCheckout

boolean

Whether this checkout is for testing purposes only (relevant only for in-app purchases). 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)

Response Object

Get Url Response

NAME
TYPE
DESCRIPTION
checkoutUrl

string

Wix checkout URL based on the parameters in the request

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

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"}
)}