About the Wix Stores Inventory Items V3 API

The Inventory Items API allows you to manage inventories for Wix Stores.

This API provides extensive functionalities to handle inventory items across multiple products, variants and in multiple locations, ensuring that store owners can track and update their stock levels seamlessly.

With the Wix Inventory Items API, you can:

Manage and update inventory items, ensuring accurate stock levels and availability.
Retrieve information about existing inventory items.

Before you begin

It’s important to note the following point before starting to code:

You must call getCatalogVersion() to get the site's Stores catalog version before using any of the Inventory Items V3 API methods. Based on the response, you must then use either the original Inventory API or the Inventory Items V3 API.

Terminology

Tracking Method: Specifies whether an inventory item is available for sale without quantity tracking or tracks the current quantity left in inventory.
Pre Order: A status indicating that an item is available to be ordered before it is in stock, with shipments occurring once inventory becomes available.
Location: Learn more about Stores Locations.

Did this help?

Setup

To use the InventoryItemsV3 API, install the @wix/stores package using npm or Yarn:

Copy

Then import { inventoryItemsV3 } from @wix/stores:

Copy

Did this help?

bulkCreateInventoryItems( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates multiple inventory items.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

inventoryItemsArray<InventoryItem>Required

Inventory items to create.

optionsBulkCreateInventoryItemsOptions

Returns

Return Type:Promise<BulkCreateInventoryItemsResponse>

Example shown:

bulkCreateInventoryItems: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkDecrementInventoryItems( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Decrements quantities of multiple inventory items.

Notes::

trackQuantity must be true to allow for decrementing the quantity.
If you pass restrictInventory: true and the decrementData.decrementBy amount is greater than the current quantity in stock, the request will fail with an INSUFFICIENT_INVENTORY error.
Pass restrictInventory: false to allow for negative quantities.
If you pass preorderRequest: true and the item is available for preorder, the item's preorderCounter will increase and the item's quantity will stay the same.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

decrementDataArray<DecrementDataById>Required

Inventory item IDs and decrement data.

optionsBulkDecrementInventoryItemsOptions

Returns

Return Type:Promise<BulkDecrementInventoryItemsResponse>

Example shown:

bulkDecrementInventoryItems: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkDecrementInventoryItemsByVariantAndLocation( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Decrements quantities of multiple inventory items by variant and location.

Notes::

trackQuantity must be true to allow for decrementing the quantity.
If you pass restrictInventory: true and the decrementData.decrementBy amount is greater than the current quantity in stock, the request will fail with an INSUFFICIENT_INVENTORY error.
Pass restrictInventory: false to allow for negative quantities.
If you pass preorderRequest: true and the item is available for preorder, the item's preorderCounter will increase and the item's quantity will stay the same.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

decrementDataArray<DecrementDataByVariantAndLocation>Required

Variant and location IDs, as well as decrement data.

optionsBulkDecrementInventoryItemsByVariantAndLocationOptions

Returns

Return Type:Promise<BulkDecrementInventoryItemsByVariantAndLocationResponse>

Example shown:

bulkDecrementInventoryItemsByVariantAndLocation: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkDeleteInventoryItems( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes multiple inventory items.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

inventoryItemIdsArray<string>Required

IDs of inventory items to delete.

Returns

Return Type:Promise<BulkDeleteInventoryItemsResponse>

Example shown:

bulkDeleteInventoryItems: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkIncrementInventoryItems( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Increments quantities of multiple inventory items.

Note: trackQuantity must be true to allow for incrementing the quantity.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

incrementDataArray<IncrementDataById>Required

Inventory item IDs and increment data.

optionsBulkIncrementInventoryItemsOptions

Returns

Return Type:Promise<BulkIncrementInventoryItemsResponse>

Example shown:

bulkIncrementInventoryItems: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkIncrementInventoryItemsByVariantAndLocation( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Increments quantities of multiple inventory items by variant and location.

Note: trackQuantity must be true to allow for incrementing the quantity.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

incrementDataArray<IncrementDataByVariantAndLocation>Required

Variant and location IDs, as well as increment data.

optionsBulkIncrementInventoryItemsByVariantAndLocationOptions

Returns

Return Type:Promise<BulkIncrementInventoryItemsByVariantAndLocationResponse>

Example shown:

bulkIncrementInventoryItemsByVariantAndLocation: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkUpdateInventoryItems( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates multiple inventory items.

Each time an inventory item is updated, revision increments by 1. The current revision must be passed when updating an inventory item. This ensures you're working with the latest inventory item and prevents unintended overwrites.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

inventoryItemsArray<MaskedInventoryItem>Required

Inventory items to update.

optionsBulkUpdateInventoryItemsOptions

Returns

Return Type:Promise<BulkUpdateInventoryItemsResponse>

Example shown:

bulkUpdateInventoryItems: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

bulkUpdateInventoryItemsByFilter( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Updates multiple inventory items, given the provided filter.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

filterRecord<string, any>Required

Filter object.

optionsBulkUpdateInventoryItemsByFilterOptions

Returns

Return Type:Promise<BulkUpdateInventoryItemsByFilterResponse>

Example shown:

bulkUpdateInventoryItemsByFilter: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

createInventoryItem( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates an inventory item. The combination of variantId and locationId is unique.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

inventoryItemInventoryItemRequired

Inventory item to create.

Returns

Return Type:Promise<InventoryItem>

Example shown:

createInventoryItem: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

deleteInventoryItem( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Deletes an inventory item.

Authentication

When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

inventoryItemIdstringRequired

Inventory item ID.

Example shown:

deleteInventoryItem: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getInventoryItem( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves an inventory item.

Permissions

Learn more about app permissions.

Method Declaration

Copy

Method Parameters

inventoryItemIdstringRequired

Inventory item ID.

Returns

Return Type:Promise<InventoryItem>

Example shown:

getInventoryItem: Wix-hosted

JavaScript

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?