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

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
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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function addProductMedia(_id: string, media: Array<MediaDataForWrite>): Promise<void>
Method Parameters
_idstringRequired

Product ID.

mediaArray<MediaDataForWrite>Required

Sources of media items already uploaded to the Wix site.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function addProductMediaToChoices(_id: string, media: Array<MediaAssignmentToChoice>): Promise<void>
Method Parameters
_idstringRequired

Product ID.

mediaArray<MediaAssignmentToChoice>Required

Product media items and the choices to add the media to.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function addProductsToCollection(_id: string, productIds: Array<string>): Promise<void>
Method Parameters
_idstringRequired

Collection ID.

productIdsArray<string>Required

IDs of the products to add to the collection, separated by commas.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function bulkAdjustProductProperty(adjust: AdjustValue, ids: Array<string>): Promise<BulkAdjustProductPropertiesResponse>
Method Parameters
adjustAdjustValueRequired

Numerical property to adjust.

idsArray<string>Required

Product IDs.

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function bulkUpdateProductsProperty(ids: Array<string>, set: SetValue): Promise<BulkUpdateProductsResponse>
Method Parameters
idsArray<string>Required

Product IDs.

setSetValueRequired

Field to update.

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function createCollection(collection: Collection): Promise<CreateCollectionResponse>
Method Parameters
collectionCollectionRequired

Collection info.

Returns
Return Type:Promise<CreateCollectionResponse>
Was this helpful?
Yes
No
createProduct( )

Creates a new product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function createProduct(product: Product): Promise<CreateProductResponse>
Method Parameters
productProductRequired

Product information.

Returns
Return Type:Promise<CreateProductResponse>
Was this helpful?
Yes
No
deleteCollection( )

Deletes a collection.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function deleteCollection(_id: string): Promise<void>
Method Parameters
_idstringRequired

ID of the collection to delete.

Was this helpful?
Yes
No
deleteProduct( )

Deletes a product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function deleteProduct(_id: string): Promise<void>
Method Parameters
_idstringRequired

ID of the product to delete.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function deleteProductOptions(_id: string): Promise<void>
Method Parameters
_idstringRequired

ID of the product with options to delete.

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 Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function getCollectionBySlug(slug: string): Promise<GetCollectionBySlugResponse>
Method Parameters
slugstringRequired

Slug of the collection to retrieve.

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function getProduct(_id: string, options: GetProductOptions): Promise<GetProductResponse>
Method Parameters
_idstringRequired

Requested product ID.

optionsGetProductOptions
Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function getProductOptionsAvailability(_id: string, options: ): Promise<ProductOptionsAvailabilityResponse>
Method Parameters
_idstringRequired

Requested product ID.

optionsRecord<string, string>Required

Array containing the selected options. For example, ["color": "Blue", "size": "Large"].

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function getStoreVariant(_id: string): Promise<GetStoreVariantResponse>
Method Parameters
_idstringRequired

Store variant ID. Comprised of the productId and the variantId, separated by a hyphen. For example, {productId}-{variantId}.

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function queryProductVariants(_id: string, options: QueryProductVariantsOptions): Promise<QueryProductVariantsResponse>
Method Parameters
_idstringRequired

Requested product ID.

optionsQueryProductVariantsOptions
Returns
Return Type:Promise<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.

Returns a list of up to 100 products, given the provided paging, sorting and filtering.

PROPERTYSUPPORTED FILTERS & SORTING
_ideq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()
nameeq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()
slugeq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()
productTypeeq(),ne(),exists(),in(),hasSome(),ascending(),descending()
descriptioneq(),ne(),exists(),in(),hasSome(),startsWith()
skueq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()
priceeq(),ne(),exists(),in(),hasSome(),ascending(),descending()
priceData.priceeq(),ne(),exists(),in(),hasSome(),lt(),le(),gt(),ge(),ascending(),descending()
numericIdeq(),ne(),exists(),in(),hasSome(),lt(),le(),gt(),ge(),ascending(),descending()
collectionIdseq(),ne(),exists(),in(),hasSome(),hasAll()
lastUpdatedeq(),ne(),exists(),in(),hasSome(),lt(),le(),gt(),ge(),ascending(),descending()
_createdDateeq(),ne(),exists(),in(),hasSome(),lt(),le(),gt(),ge()

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function queryProducts(): ProductsQueryBuilder
Request
This method does not take any parameters
Returns
Return Type: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 Stores - all permissions
Manage Products
Read Stores - all read permissions
Read Products
Manage Orders
Learn more about permission scopes.
Copy
function queryStoreVariants(query: PlatformQuery): Promise<QueryStoreVariantsResponse>
Method Parameters
queryPlatformQueryRequired

Query options.

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function removeBrand(_id: string): Promise<void>
Method Parameters
_idstringRequired

Product ID.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function removeProductMedia(_id: string, mediaIds: Array<string>): Promise<void>
Method Parameters
_idstringRequired

Product ID.

mediaIdsArray<string>Required

List of media IDs to remove. Pass an empty array to delete all media items for the product.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function removeProductMediaFromChoices(_id: string, media: Array<MediaAssignmentToChoice>): Promise<void>
Method Parameters
_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.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function removeProductsFromCollection(_id: string, productIds: Array<string>): Promise<void>
Method Parameters
_idstringRequired

ID of the collection from which to remove products.

productIdsArray<string>Required

IDs of the products to remove from the collection.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function removeRibbon(_id: string): Promise<void>
Method Parameters
_idstringRequired

Product ID.

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function resetAllProductVariantData(_id: string): Promise<void>
Method Parameters
_idstringRequired

Product ID.

Was this helpful?
Yes
No
updateCollection( )

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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function updateCollection(_id: string, collection: UpdateCollection): Promise<UpdateCollectionResponse>
Method Parameters
_idstringRequired

Collection ID (generated automatically by the catalog).

collectionUpdateCollectionRequired

Collection info to update.

Returns
Return Type:Promise<UpdateCollectionResponse>
Was this helpful?
Yes
No
updateProduct( )

Updates specified fields in a product.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function updateProduct(_id: string, product: UpdateProduct): Promise<UpdateProductResponse>
Method Parameters
_idstringRequired

Product ID (generated automatically by the catalog).

productUpdateProductRequired

Product info to update.

Returns
Return Type:Promise<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 Stores - all permissions
Manage Products
Learn more about permission scopes.
Copy
function updateProductVariants(_id: string, variants: Array<VariantOverride>): Promise<UpdateVariantsResponse>
Method Parameters
_idstringRequired

ID of the product with managed variants.

variantsArray<VariantOverride>Required

Variant info to update.

Returns
Return Type:Promise<UpdateVariantsResponse>
Was this helpful?
Yes
No