Setup

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

Copy
1
npm install @wix/stores

or

Copy
1
yarn add @wix/stores

Then import { products } from @wix/stores:

Copy
1
import { products } from '@wix/stores'
Was this helpful?
Yes
No

Introduction

 

The Stores Products API allows you to manage products to sell.

With the Products API, you can:

  • create and update products
  • add media, such as images or GIFs, to products

See Managing Products for more information.

Terminology

  • Options: Property types that customers can select within the specific product. For example, color and size.
  • Choices: Available selections within each option. For example, red, green, and blue as choices under the color option.
  • Variants: Combinations of different product options and choices. For example, a red shirt in size large.
Was this helpful?
Yes
No

addProductMedia( )

Adds media items to a specified product, either via URL or existing media ID.

NOTE: The URL is not validated and no event is triggered to indicate if the media was added successfully.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID.

mediaArray<MediaDataForWrite>Required
Sources of media items already uploaded to the Wix site.
Response Object
void
Was this helpful?
Yes
No

addProductMediaToChoices( )

Links media items that are already associated with a specific product to a choice within the same product.

Media items can only be set for choices within one option at a time - e.g., if you set media items for some or all of the choices within the Colors option (blue, green, and red), you won't be able to also assign media items to choices within the Size option (S, M, and L).

To remove all existing media items, call the Remove Product Media From Choices endpoint.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID.

mediaArray<MediaAssignmentToChoice>Required
Product media items and the choices to add the media to.
Response Object
void
Was this helpful?
Yes
No

addProductsToCollection( )

Adds products to a specified collection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Collection ID.

productIdsArray<string>Required
IDs of the products to add to the collection, separated by commas.
Response Object
void
Was this helpful?
Yes
No

bulkAdjustProductProperty( )

Developer Preview

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

Adjusts a specified numerical property for up to 100 products at a time. The property can be increased or decreased either by percentage or amount.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
adjustAdjustValueRequired
Numerical property to adjust.

idsArray<string>Required
Product IDs.
Response Object
BulkAdjustProductPropertiesResponse
Was this helpful?
Yes
No

bulkUpdateProductsProperty( )

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 a specified property for up to 100 products at a time.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
idsArray<string>Required
Product IDs.

setSetValueRequired
Field to update.
Response Object
BulkUpdateProductsResponse
Was this helpful?
Yes
No

createCollection( )

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 a new collection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
collectionCollectionRequired
Collection info.
Response Object
CreateCollectionResponse
Was this helpful?
Yes
No

createProduct( )

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 a new product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
productProductRequired
Product information.
Response Object
CreateProductResponse
Was this helpful?
Yes
No

deleteCollection( )

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 a collection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
ID of the collection to delete.
Response Object
void
Was this helpful?
Yes
No

deleteProduct( )

Deletes a product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
ID of the product to delete.
Response Object
void
Was this helpful?
Yes
No

deleteProductOptions( )

Delete all options from a specific product. Only available when variant management is disabled.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
ID of the product with options to delete.
Response Object
void
Was this helpful?
Yes
No

getCollectionBySlug( )

Retrieves a collection with the provided slug.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Params
slugstringRequired
Slug of the collection to retrieve.
Response Object
GetCollectionBySlugResponse
Was this helpful?
Yes
No

getProduct( )

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 a product with the provided ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Params
_idstringRequired
Requested product ID.

optionsGetProductOptions
Response Object
GetProductResponse
Was this helpful?
Yes
No

getProductOptionsAvailability( )

Gets the availability of relevant product variants based on the product ID and selections provided. See Use Cases for an example.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Params
_idstringRequired
Requested product ID.

optionsRecord<string, string>Required
Array containing the selected options. For example, ["color": "Blue", "size": "Large"].
Response Object
ProductOptionsAvailabilityResponse
Was this helpful?
Yes
No

getStoreVariant( )

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 a store variant with the provided ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Params
_idstringRequired
Store variant ID. Comprised of the productId and the variantId, separated by a hyphen. For example, {productId}-{variantId}.
Response Object
GetStoreVariantResponse
Was this helpful?
Yes
No

queryProductVariants( )

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 product variants, based on either choices (option-choice key-value pairs) or variant IDs. See Stores Pagination for more information.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Params
_idstringRequired
Requested product ID.

optionsQueryProductVariantsOptions
Response Object
QueryProductVariantsResponse
Was this helpful?
Yes
No

queryProducts( )

Developer Preview

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Request
This method does not take any parameters
Response Object
ProductsQueryBuilder
Was this helpful?
Yes
No

queryStoreVariants( )

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 up to 100 store variants, given the provided paging, filtering, and sorting.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Products
Read Products
Learn more about permission scopes.
Params
queryPlatformQueryRequired
Query options.
Response Object
QueryStoreVariantsResponse
Was this helpful?
Yes
No

removeBrand( )

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 a product's brand.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID.
Response Object
void
Was this helpful?
Yes
No

removeProductMedia( )

Removes specified media items from a product. Pass an empty array to remove all media items.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID.

mediaIdsArray<string>Required
List of media IDs to remove. Pass an empty array to delete all media items for the product.
Response Object
void
Was this helpful?
Yes
No

removeProductMediaFromChoices( )

Removes media items from all or some of a product's choices. (Media items can only be set for choices within one option at a time - e.g., if you set media items for some or all of the choices within the Colors option (blue, green, and red), you won't be able to also assign media items to choices within the Size option (S, M, and L).)

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID from whose choices to remove media items.

mediaArray<MediaAssignmentToChoice>Required
Media to remove from choices. If an empty array is passed, all media will be removed from all choices for the given product.
Response Object
void
Was this helpful?
Yes
No

removeProductsFromCollection( )

Deletes products from a specified collection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
ID of the collection from which to remove products.

productIdsArray<string>Required
IDs of the products to remove from the collection.
Response Object
void
Was this helpful?
Yes
No

removeRibbon( )

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 a product's ribbon.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID.
Response Object
void
Was this helpful?
Yes
No

resetAllProductVariantData( )

Developer Preview

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

Resets the data (such as the price and the weight) of all variants for a given product to their default values.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID.
Response Object
void
Was this helpful?
Yes
No

updateCollection( )

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 specified properties of a collection. To add products to a collection, call the addProductsToCollection function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Collection ID (generated automatically by the catalog).

collectionUpdateCollectionRequired
Collection info to update.
Response Object
UpdateCollectionResponse
Was this helpful?
Yes
No

updateProduct( )

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 specified fields in a product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
Product ID (generated automatically by the catalog).

productUpdateProductRequired
Product info to update.
Response Object
UpdateProductResponse
Was this helpful?
Yes
No

updateProductVariants( )

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 variants of a specified product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Products
Learn more about permission scopes.
Params
_idstringRequired
ID of the product with managed variants.

variantsArray<VariantOverride>Required
Variant info to update.
Response Object
UpdateVariantsResponse
Was this helpful?
Yes
No