Search API library /

Generate a test token to explore our APIs

Getting Started

Overview

You can use our various REST APIs to access Wix user's site data (e.g., contacts, orders, etc.). Our APIs use standard HTTPS terminology and OAuth authentication, and return JSON-encoded responses. To use our APIs, site owners must grant you explicit permission to collect this data when installing your app on their site.

Important:
Use of Wix APIs are subject to the Wix App Market Guidelines.

Tip:
There's more information available in our FAQ.

Authentication

When a site owner installs your app, they will grant you permission to collect site data during the installation flow, which is based on the settings you provide in the Wix Developers Center. You will receive an authorization code which you will use to request an access token and a refresh token. Then you’ll pass the access token as an authorization header in the API call.

The OAuth Flow

We use OAuth 2.0 to authorize you to access our APIs and receive webhooks.

Note:
You’ll need to set up OAuth, Permissions, and Webhooks settings in the Wix Developers Center.

oauth flow diagram

Step 1 (Optional): User Installs Your App

If the user chooses to install your app from within the Wix App Market, we redirect users to the App URL you defined in the Wix Developers Center. We include a token query parameter when we direct users to your App URL (we use it to keep track of the user as they go through the OAuth flow).

Note:
This redirect to the App URL is a back-end process only. The user shouldn't have to log in or sign up here - send them straight to the authorization request step described next.

Important:
If the user installs your app from your own platform, skip this step and go straight to step 2.

Step 2: App Sends Users to Authorize the App

Your app should redirect users to the URL below so that we can ask them to approve a list of permissions your app is requesting (based on the permissions you added in the Wix Developers Center).


Redirect users to the following URL:
https://www.wix.com/app-oauth-installation/consent


Send the following query parameters with the URL above:

  • token (required during installation from Wix only): The token you received as a query parameter to the App URL. We use it to keep track of users as they go through the OAuth flow.
  • appId: Your App ID, as defined in the Wix Developers Center.
  • redirectUrl: One of the redirect URLs you defined in the Wix Developers Center. You may define a separate redirect URL for each workflow (e.g., from the App Market and from your platform).
  • state (optional): You can add a unique string to identify users that were authenticated in the previous step. This is how you'll identify the user when we send them to your redirect URL.

    Important:
    Every redirect URL your app might use must be defined in the Wix Developers Center in advance.

Step 2a: User Authorizes the App

When the user approves the permissions your app has requested, Wix will continue to the next step.

Step 3: Wix Redirects the User to App Server With an Authorization Code

Wix will redirect the user back to your specified redirect_url along the following query parameters:

  • code - A temporary authorization code. You’ll need this later, to request an access token to use our API.
  • state - The same value in case you provided one in the previous step. If the states don't match, the request may have been created by a third party and you should abort the process.
  • instanceId - The unique ID created for your app installation in the user specific site. All of your app’s components in the site share the same instance ID. Your app should always identify users using the instance ID.

Important:
If your app requires user login or signup - do so here.

Note:
After this step, the user is done. However, your app still has some work to do.

Step 4: App Submits the Authorization Code

Once the user completes the installation process and gives your app permission to access their data, use the temporary authorization code we sent you, together with your secret key, to request an access token and a refresh token. (The access token is only valid for 10 minutes.)

You can find your secret key in the Wix Developers Center.

Important:
This request must be a secure, server-to-server request.

Exchange the temporary authorization code for an access token using the [OAuth > Acces Token Request](https://dev.wix.com/api/authorization#oauth-2.access-token-request) API method:
curl -X POST \
  https://www.wix.com/oauth/access \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "authorization_code",
    "client_id": <APP_ID>,
    "client_secret": <APP_SECRET>,
    "code": <AUTH_CODE>
  }

Step 5: App Receives Access and Refresh Tokens

Wix will respond to your request in step 4 with a JSON response containing an access token and a refresh token (These tokens are not relevant for webhooks):

{
   "refresh_token": <REFRESH_TOKEN>,
   "access_token": <FRESH_ACCESS_TOKEN>
}

Note:
Request a new access token every time you call an API. Access tokens expire after 10 minutes. Use your refresh token to request a new access token.

Step 5a: App Completes the OAuth Flow

  • When users add the app from the Wix App Market:
    Your app should redirect users to the following URL so that we can complete the OAuth flow: https://www.wix.com/app-oauth-installation/token-received The OAuth flow is now complete, and we’ll close the window.
  • When users add the app from your platform:
    Your app should close the window it opened, and redirect the user to their dashboard or home page.

Step 6: App Requests Protected Data

Follow our API Reference section to request the user's protected data, with a fresh access token as the authorization header.

Permissions

The permissions you select in the Wix Developers Center will dictate which type of authorization site owners will provide and which data you can access. Site owners will be asked to authorize the permissions you've requested during the installation flow.

Important:
Never ask for more permissions than the ones required for your app to function as intended. Determine the scope of your app permissions thoroughly before requesting permissions in the Wix Developers Center.

Webhooks

When you register for webhooks in the Wix Developers Center, and you’ve configured your OAuth and Permissions settings correctly, Wix will send an HTTPS POST request to your server URL with the relevant data when an event occurs.

The event’s data is included in the body of the request as a JSON Web Token (JWT).
The data received will vary by the type of event, but the following will always be included:

  • instanceId: The App Instance ID. This is the unique identifier of the app within the website.
  • eventType: A description of the event type, e.g., OrderEvent.

Data Payloads

When you receive a data payload from Wix, it will include a header called 'digest' - the header will hold a JSON web token (JWT) with the signed data. (Here's a sample decoded JWT.)

Use your app’s public key to verify that the data was sent by Wix.

Errors

When you call an API, the response you'll receive will include a status code. If something went wrong, you'll receive an error code that defines the type of error that occurred.

HTTP Status CodeDescription
200 - OKSuccess
400 - Bad RequestOne or more request parameters is wrong or missing, or you didn't not pass validation
401 - UnauthorizedThe system was not able to authenticate you (missing or incorrect Authorization header, expired token, etc.)
403 - ForbiddenThe system authenticated you, but you don’t have permissions to call this API
404 - Not foundResource not found / doesn't exist
409 - ConflictThe resource you are attempting to create already exists
429 - Too many requestsResource usage was exhausted (e.g., a previously used one-time-token)
500 - Internal server errorAn error occurred on Wix's server, try again later
501 - Not implementedThe endpoint has not been implemented yet
503 - Service unavailableThe service that you’re trying to access is temporarily unavailable. Try again later
504 - Gateway timeoutThe underlying service did not respond in a timely manner. Try again later

API Query Language

General

The query language described in this document CAN be implemented partially or in full by an API supporting query capabilities.

The style of the QL is heavily influenced by MongoQL, because it is:

  • A structured QL, written as JSON, and therefore easy to parse (e.g. comparing to SQL)
  • Easy to extend
  • Readable
  • Well-known and common

Some of the protobuf definitions listed below already exist in the common proto repository and you should simply import it instead of redefining it in your service.

Syntax

A query object consists of 5 (optional) parts:

  • Filter - which entities to return
  • Sort - in what order
  • Paging - return only part of the matched entities
  • Fields - return only part of each entity (a.k.a. projection)
  • Fieldset - a predefined set of fields with common use (i.e. named projection). This is a shorthand provided by the API for specifying each field name.

Each query is always a single JSON: { }
An empty json will return all records in no specific order. An application can decide to return a subset of the records (default paging behavior)

The query object can define a key for each of the above parts:

{
  filter: { … },
  sort: [ … ],
  paging: { … },
  fields: [ … ],
  fieldset: ["xx"…]
}

The Filter Section

The filter section is a single json object { } with the following rules:

Equality

Use the format {<field>: <value>, ...} to specify equality condition. E.g. the query {status: "X"} will match all entities with a status equal to "X"

Operators

Use operators in the following format: {<field>: {<operator>:<value>}, ...}.
E.g. the query {status: {$in: ["X", "Y"]}} will match all entities that have status set to "X" or "Y"
The following operators are supported:

Comparison
  • $eq - matches values that are equal to a specified value.
  • $gt - Matches values that are greater than a specified value.
  • $gte - Matches values that are greater than or equal to a specified value.
  • $in - Matches any of the values specified in an array.
  • $lt - Matches values that are less than a specified value.
  • $lte - Matches values that are less than or equal to a specified value.
  • $ne - Matches all values that are not equal to a specified value.
  • $nin - Matches none of the values specified in an array.
  • $begins - Matches strings that begin with a specified value (NOT case sensitive).
  • $ends - Matches strings that ends with a specified value (NOT case insensitive).
  • $contains - Matches strings that contain a specified value (NOT case sensitive).
Logical
  • $and - Joins query clauses with a logical AND, returns all documents that match the conditions of both clauses.
  • $not - Inverts the effect of a query expression, returns documents that do not match the query expression.
  • $or - Joins query clauses with a logical OR, returns all documents that match the conditions of either clause.
Element
  • $exists - Matches documents that have the specified field.
Array
  • $all - Matches arrays that contain all elements specified in the query.
  • $any - Matches arrays that contain at least one element specified in the query

Sample Queries

In the following example, the compound query returns all entities where the status equals "A" and either qty is less than 30 or item starts with the character p:

{
  status: "A",
  $or: [{qty: {$lt: 30}}, {item: {$begins: "p"}}]
}

The following example queries entities where the field tags value is an array with exactly two elements, "red" and "blank", in the specified order:

{ tags: ["red", "blank"] }

The following example queries for all entities where tags is an array that contains the string "red" as one of its elements, or that tags is the string "red":

{tags: "red" } 

The following query matches entities that do not contain the item field, or where the item field has no value:

{item: {$exists: false }} 

The Sort Section

The sort section is an array of field names and sort direction. If the direction is not specified, it will be sorted in ascending order:

sort: [{"fieldName":"sortField1"},{"fieldName":"sortField2","direction":"DESC"}]

The Paging Section

The paging section describes the size of the data set to return (i.e. page size), and how many "records" to skip. The following will return records 41-60. I.e. page number 3 with each page being 20 records:

paging: { limit: 20, offset: 40 }

The Fields Section

The fields section is an array of field names/paths to return. If a pointed field of the DTO contains an object, the entire sub-object will be returned. Subset of sub-objects can be returned by using dot notation. In this example the returned entities will contain first_name from name sub-object and the entire address object

fields: ["name.firstName", "address"]

The Fieldset Section

An API may decide to provide named projectios to save its clients the bother of writing the names of the fields in common cases.
For example, Contacts can implement a fieldset named common that contains only first name, last name, primary email and phone number. To use fieldset, the client should specify its name. If both fieldset and fields sections exist, the union of both will take effect. E.g.

fieldset: ["common"]

Query Response

The response for a query request should be an object with the following structure:

{
  results: [...], //instead of 'results' you can use more explicit name like 'invoices'
  metadata: {  //this is page 2 
    items: 25,
    offset: 25
  },
  totalResults: 420
}