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

About Wix Stores

Wix enables site owners to quickly and easily create and manage an online store for physical and/or digital products on their site. Read more about the Wix Stores features.

Terminology

  • The catalog is a complete list of all the store‚Äôs products - compiled automatically.
  • Collections are themed groupings of items for purchase that a store owner can create to organize their products (e.g., Spring 2019, Running shoes, etc.). Products can belong to multiple collections.
  • Options are property types that customers can select within the specific product - e.g., color and size.
  • Selections are the types available within each option - e.g., red and green selections under the Color option.
  • Choices are the specific choices the customer has made within a selection - e.g., choosing the red Selection triggers the red Choice.
  • Variants are combinations of different product choices - e.g., a red shirt in size large. A variant can override the following values from the parent product:
    • Price
    • SKU
    • Weight
    • Inventory

Was this helpful?

Pagination

The standard Wix API pagination includes:

limit: amount of items per response (defaults will be defined per use case)
offset: number of items to skip

The following example:

"query": {
"paging": {
"limit": 100,
"offset": 20
}
}
Copy Code

Should return items 21-120 in the collection.

Wix Stores query endpoints are designed to handle a max of 10k data items. Therefore, if a user's store includes ~10k relevant items (e.g., products, inventory items), limit and offset may fail.

Instead, filter by numericId (query products, query inventory) or number (query orders) and sort in ascending order:

"query": {
"sort": [{"numericId": "asc"}],
}
Copy Code

Then copy the last numericId/number sent in this call and call the endpoint again:

"query":{
"sort": [{"numericId": "asc"}],
"filter": {
"numericId": {
"$gt": <last numeric id>
}
}
}
Copy Code

Continue until you receive an empty JSON as a response.

Important:
Escape the JSON strings in your query parameters.

Was this helpful?

Rich Text

Select parameters currently accept values with rich text. The following rich text formatting is accepted:

<p><strong>This is bolded text</strong></p>
<p><u>This is underlined text</u></p>
<p><span style=\"color:#cb2026\">This is red text</span></p>
<p><span style=\"color:#000000;\"><span style=\"background-color:#ce5028;\">This is black text with a red background</span></span></p>
<p><a href=\"http://www.google.com\" target=\"_blank\">This is a link</a></p>

<ul>
<li>This is a bullet</li>
<li>This is a second bullet</li>
</ul>
Copy Code
<ol>
<li>This is a numbered list item</li>
<li>This is a second numbered list item</li>
</ol>
Copy Code

Was this helpful?

Carts

Read and Write carts from Wix Stores, produce cart lifecycle events

Catalog

Read the products from Wix Stores catalog

Inventory

Read & Write inventory from Wix Stores Inventory Learn more.

Guides

Additional information about this section

Main Entity

The API's main object

Endpoints

The endpoints exposed by this API

  • POST
  • POST

    Returns a list of up inventory items, given the provided paging, sorting and filtering. See Stores Pagination for more information.

  • PATCH

    Updates product inventory, including total quantity, whether the product is in stock, and whether the product inventory is tracked

  • POST

    Subtracts a set number of items from inventory (atomic). For use when the current inventory quantity is unknown or irrelevant (e.g., updating inventory when an ...

About the Inventory API

This service allows you to query and modify the inventory for your store's products.

(In the future, this service might be used to manage inventory for other things.)

Terminology

  • Item Represents a product from the catalog.
  • Variant A product variant. The inventory is managed per variant.

Was this helpful?

Using the Inventory API

Step 1 - Get the product ID (Get Product endpoint)

curl 'https://www.wixapis.com/stores/v1/products/{productId}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Copy Code

From the response, take the inventoryItemId. You will use this ID to query the inventory system.

Step 2 - Update the inventory item's status (Update Inventory Status endpoint)

curl 'https://www.wixapis.com/stores/v1/inventoryItems/{inventoryItemId}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Copy Code

From the result, you can see whether inventory is being tracked for this product:

{
"item": {
"id": "4d55c9b5-7f00-1dd8-c213-272615328354",
"externalId": "b2aa364a-80ff-e227-3dec-d8d9eacd7cab",
"trackInventory": false
}
}
json | Copy Code

Or change the product to track or not track inventory:

curl 'https://www.wixapis.com/stores/v1/inventoryItems/{inventoryItemId}' -X PATCH --data-binary '{"item": {"trackInventory": true}}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Copy Code

Step 3 - Query the product variants (Query Inventory endpoint) - inventory is trakced per variant

This query will return all variants, unless you filter for specific ones.

curl 'https://www.wixapis.com/stores/v1/products/{productId}/variants/query' --data-binary '{}' -H 'Content-Type: application/json' -H 'Authorization: XXXX'
Copy Code

This is an example for what the result would be like for a product that has no options. From the below response, you can extract the variant ID - 00000000-0000-0000-0000-000000000000

{
"variants": [
{
"id": "00000000-0000-0000-0000-000000000000",
"choices": {
},
"variant": {
"price": {
"currency": "USD",
"price": 0.0,
"discountedPrice": 0.0,
"formatted": {
"price": "$0.00",
"discountedPrice": "$0.00"
}
},
"sku": "",
"visible": true
}
}
],
"metadata": {
"items": 1,
"offset": 0
}
}
json | Copy Code

Step 4 - Use variant ID to get or update the variant inventory (Get Inventory Variants endpoint)

curl 'https://www.wixapis.com/stores/v1/inventoryItems/{inventoryItemId}/variant/{variantId}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Copy Code

From the result, you can see whether the variant is in stock or not. If inventory is being tracked, you can get the exact quantity

{
"variant": {
"itemId": "4d55c9b5-7f00-1dd8-c213-272615328354",
"variantId": "00000000-0000-0000-0000-000000000000",
"inStock": true,
"quantity": 5
}
}
json | Copy Code

And you can also update the inventory. For a non-tracked product, you should update inStock:

curl 'https://www.wixapis.com/stores/v1/inventoryItems/{inventoryItemId}/variant/{variantId}' -X PATCH --data-binary '{"variant": {"inStock": true}}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Copy Code

For tracked products, you should update quantity:

curl 'https://www.wixapis.com/stores/v1/inventoryItems/{inventoryItemId}/variant/{variantId}' -X PATCH --data-binary '{"variant": {"quantity": 5}}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Copy Code

Was this helpful?

Inventory Item Object

Attributes

NAME
TYPE
DESCRIPTION
id

string

Inventory item ID

externalId

string

Product ID

trackInventory

boolean

Whether inventory is being tracked

Was this helpful?

Get Inventory Variants

Authorization

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

Permissions

The API requires WIX_STORES.READ_INVENTORY

POST

https://www.wixapis.com/stores/v2/inventoryItems/{inventoryId}/getVariants

Path Params

NAME
TYPE
DESCRIPTION
inventoryId
Required

string

Inventory item ID

Body Params

NAME
TYPE
DESCRIPTION
variantIds

Array<string>

Variant IDs to query for this inventory item (optional)

Response Object

Get Inventory Variants Response

NAME
TYPE
DESCRIPTION
inventoryItem

object

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Request

curl

Copy Code
1curl -X POST https://www.wixapis.com/stores/v2/inventoryItems/be547028-fb08-b962-75e8-3f3e56da9ee3/getVariants \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: <AUTH>' \
4 --data-binary '
5 {}
6 }'

Response

json

1
2{"inventoryItem": {
3 "id": "be547028-fb08-b962-75e8-3f3e56da9ee3",
4 "externalId": "41ab8fd7-04f7-469d-8a17-c0c1a925611c",
5 "trackQuantity": false,
6 "variants": [
7 {
8 "variantId": "00000000-0000-0001-0005-9a596c8e6f10",
9 "inStock": true,
10 "quantity": 0
11 },
12 {
13 "variantId": "00000000-0000-0002-0005-9a596c8e6f10",
14 "inStock": true,
15 "quantity": 0
16 }
17 ],
18 "lastUpdated": "2020-01-29T09:22:18.599Z",
19 "numericId": "1576742838020000"
20}}

Query Inventory

Returns a list of up inventory items, given the provided paging, sorting and filtering.
See Stores Pagination for more information.

Authorization

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

Permissions

The API requires WIX_STORES.READ_INVENTORY

POST

https://www.wixapis.com/stores/v2/inventoryItems/query

Body Params

NAME
TYPE
DESCRIPTION
query

object

Response Object

Query Inventory Response

NAME
TYPE
DESCRIPTION
inventoryItems

Array<object>

metadata

object

totalResults

integer

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example 1

Request

curl

Copy Code
1curl -X POST https://www.wixapis.com/stores/v2/inventoryItems/query \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: <AUTH>' \
4 --data-binary '
5 {}
6 }'

Response

json

1
2{
3 "inventoryItems": [
4 {
5 "id": "0ff8f8b0-2857-5974-193e-8283c21fde00",
6 "externalId": "f007074f-d7a8-a68b-e6c1-7d7c3de021ff",
7 "trackQuantity": false,
8 "variants": [ {
9 "variantId": "00000000-0000-0000-0000-000000000000",
10 "inStock": false,
11 "quantity": 0
12 }],
13 "lastUpdated": "2020-02-11T12:30:04.961Z",
14 "numericId": "1579429500810000"
15 },
16 {
17 "id": "be547028-fb08-b962-75e8-3f3e56da9ee3",
18 "externalId": "41ab8fd7-04f7-469d-8a17-c0c1a925611c",
19 "trackQuantity": false,
20 "variants": [
21 {
22 "variantId": "00000000-0000-0001-0005-9a596c8e6f10",
23 "inStock": true,
24 "quantity": 0
25 },
26 {
27 "variantId": "00000000-0000-0002-0005-9a596c8e6f10",
28 "inStock": true,
29 "quantity": 0
30 }
31 ],
32 "lastUpdated": "2020-01-29T09:22:18.599Z",
33 "numericId": "1576742838020000"
34 }
35 ],
36 "metadata": {
37 "items": 100,
38 "offset": 0
39 },
40 "totalResults": 2
41}
Example 2

Update Inventory Variants

Updates product inventory, including total quantity, whether the product is in stock, and whether the product inventory is tracked

Authorization

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

Permissions

The API requires WIX_STORES.MODIFY_INVENTORY

PATCH

https://www.wixapis.com/stores/v2/inventoryItems/{inventoryItem.id}

Path Params

NAME
TYPE
DESCRIPTION
inventoryItem.id
Required

string

Inventory item ID

Body Params

NAME
TYPE
DESCRIPTION
inventoryItem
Required

object

Response Object

Update Inventory Variants Response

Returns an empty object.

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Example 1

Request

curl

Copy Code
1curl -X PATCH https://www.wixapis.com/stores/v2/inventoryItems/0ff8f8b0-2857-5974-193e-8283c21fde00 \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: <AUTH>' \
4 --data-binary '
5 {
6 "inventoryItem": {
7 "trackQuantity": false,
8 "variants": [
9 {
10 "variantId": "00000000-0000-0001-0005-9a596c8e6f10",
11 "inStock": true
12 },
13 {
14 "variantId": "00000000-0000-0002-0005-9a596c8e6f10",
15 "inStock": true
16 }
17 ]
18 }
19 }'

Response

json

1
2{}
Example 2
Example 3

Decrement Inventory

Subtracts a set number of items from inventory (atomic).
For use when the current inventory quantity is unknown or irrelevant (e.g., updating inventory when an order is fulfilled).

Authorization

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

Permissions

The API requires WIX_STORES.MODIFY_INVENTORY

POST

https://www.wixapis.com/stores/v2/inventoryItems/decrement

Body Params

NAME
TYPE
DESCRIPTION
decrementData

Array<object>

Response Object

Decrement Inventory Response

Returns an empty object.

Status/Error Codes

The response will include an HTTP status code.

Was this helpful?

Request

curl

Copy Code
1curl -X POST https://www.wixapis.com/stores/v2/inventoryItems/decrement \
2 -H 'Content-Type: application/json' \
3 -H 'Authorization: <AUTH>' \
4 --data-binary '
5 {
6 "decrementData": [
7 {
8 "externalId": "f007074f-d7a8-a68b-e6c1-7d7c3de021ff",
9 "variantId": "00000000-0000-0001-0005-9ccb19c4e6f0",
10 "quantity": 2
11 }
12 ]
13 }'

Response

json

1
2{}

Inventory Item Changed Webhook

Authorization

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

Permissions

The API requires WIX_STORES.READ_INVENTORY

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
inventoryItemId

string

Inventory item ID

externalId

string

Item ID from external source

trackInventory

boolean

Whether inventory is being tracked

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

json

1
2{
3 "inventoryItemId": "81b0fdc0-ac2d-8f25-cf44-ce99d4c3f6a0",
4 "externalId": "7e4f023f-53d2-70da-30bb-31662b3c095f",
5 "trackInventory": false
6}

Inventory Variants Changed Webhook

Authorization

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

Permissions

The API requires WIX_STORES.READ_INVENTORY

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
inventoryItemId

string

Inventory item ID

externalId

string

Item ID from external source

variants

Array<object>

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

json

1
2{
3 "inventoryItemId": "81b0fdc0-ac2d-8f25-cf44-ce99d4c3f6a0",
4 "externalId": "7e4f023f-53d2-70da-30bb-31662b3c095f",
5 "variants": [
6 {
7 "id": "00000000-0000-0001-0005-918e4641acb0",
8 "oldValue": {"inStock": true},
9 "newValue": {"inStock": false}
10 },
11 {
12 "id": "00000000-0000-0003-0005-918e4641acb0",
13 "oldValue": {"inStock": true},
14 "newValue": {"inStock": false}
15 }
16 ]
17}

Orders

Read orders from Wix Stores

)}