Introduction

Note: This service plugin is currently in beta and is subject to change. Some service plugins are currently not available to all users.

The eCommerce Catalog service plugin (formerly SPI) is a service provider interface that provides functionality for implementing your own custom catalog of items and/or services to be sold on your site. Define how your custom catalog interacts with the eCommerce purchase flow in a way that is not currently supported natively by Wix. For example, you can determine the number of catalogs to choose from, provide a simplified catalog of products or services, and choose the products or services you wish to sell. The custom catalog can be used instead of, or alongside, a Wix Stores catalog.

Wix eCommerce calls the service plugin endpoint getCatalogItems() to retrieve the custom catalog's items. These items can then be displayed in dynamic product pages, as well as the cart, checkout, and order.

Learn more:

To add a service plugin

  1. Add the plugin to your site.
  2. Update the getConfig() function in the -config.js file that is added to your site during step 1.
  3. Update the getCatalogItems() function in the .js file that is added to your site during step 1.
Did this help?

getCatalogItems( )


Retrieves item data from a custom catalog.

This function is automatically called by Wix to retrieve the catalog items provided by your custom catalog plugin. This happens when certain actions are performed on the cart and/or checkout. For example, when an item is added to the cart.

Where to find getCatalogItems()

When you add the Catalog service plugin, a folder is automatically added to your site. Use the .js file in the folder to write the code to determine which catalog items to retrieve.

For more information on customizing your catalog plugin, see Velo Tutorial: eCommerce Catalog Service Plugin.

Method Declaration
Copy
function getCatalogItems(
  options: Options,
  context: Context,
): Promise<Array<CatalogItems>>;
Method Parameters
optionsOptionsRequired

Catalog and item references (IDs and additional info), weight unit, and quantities requested by Wix eCommerce.


contextContextRequired

Metadata about the request.

Returns
Return Type:Promise<Array<CatalogItems>>
Example of received `options` parameter and returned properties for `catalogItems` array
JavaScript
export const getCatalogItems = async (options) => { // Example options parameter options = { catalogReferences: [ { catalogReference: { catalogItemId: "2", appId: "7ff4b539-e3bf-4d8e-84d4-2ed180fce336", options: { options: { week: "3", }, }, }, quantity: 1, }, ], weightUnit: "LB", }; // Example of returned catalogItems array return { catalogItems: [ { catalogReference: { appId: "7ff4b539-e3bf-4d8e-84d4-2ed180fce336", catalogItemId: "2", options: { options: { week: "3", }, }, }, data: { productName: { original: "EuroCamper", translated: "EuroCamper", }, itemType: { preset: "PHYSICAL", }, price: "540", media: "wix:image://v1/11062b_7fba2fc327a04e1493f1a28213e8cae8~mv2.jpeg/camping-site#originWidth=6924&originHeight=3130", descriptionLines: [ { name: { original: "Beds", translated: "Beds", }, lineType: "PLAIN_TEXT", plainTextValue: { original: "Type: Double, Quantity: 1\nType: King, Quantity: 1", translated: "Type: Double, Quantity: 1\nType: King, Quantity: 1", }, plainText: { original: "Type: Double, Quantity: 1\nType: King, Quantity: 1", translated: "Type: Double, Quantity: 1\nType: King, Quantity: 1", }, }, { name: { original: "Size", translated: "Size", }, lineType: "PLAIN_TEXT", plainTextValue: { original: "7x3x3", translated: "7x3x3", }, plainText: { original: "7x3x3", translated: "7x3x3", }, }, { name: { original: "Description", translated: "Description", }, lineType: "PLAIN_TEXT", plainTextValue: { original: "Professional Travelers RV for road trips, Enjoy a comfortable mobile home for the best family experience !", translated: "Professional Travelers RV for road trips, Enjoy a comfortable mobile home for the best family experience !", }, plainText: { original: "Professional Travelers RV for road trips, Enjoy a comfortable mobile home for the best family experience !", translated: "Professional Travelers RV for road trips, Enjoy a comfortable mobile home for the best family experience !", }, }, { name: { original: "Additional Info", translated: "Additional Info", }, lineType: "PLAIN_TEXT", plainTextValue: { original: "Deposit fee is 40$ per item\nReturning the item: return shipping is included with your order. All\nyou have to do is re-pack the hardware and it will be picked up by\nthe shipping company at the rental end date. If you cannot be\nreached, late fees will apply.\nCancelation: Orders will receive a full refund when canceled 10\nbusiness days before the rental start date.", translated: "Deposit fee is 40$ per item\nReturning the item: return shipping is included with your order. All\nyou have to do is re-pack the hardware and it will be picked up by\nthe shipping company at the rental end date. If you cannot be\nreached, late fees will apply.\nCancelation: Orders will receive a full refund when canceled 10\nbusiness days before the rental start date.", }, plainText: { original: "Deposit fee is 40$ per item\nReturning the item: return shipping is included with your order. All\nyou have to do is re-pack the hardware and it will be picked up by\nthe shipping company at the rental end date. If you cannot be\nreached, late fees will apply.\nCancelation: Orders will receive a full refund when canceled 10\nbusiness days before the rental start date.", translated: "Deposit fee is 40$ per item\nReturning the item: return shipping is included with your order. All\nyou have to do is re-pack the hardware and it will be picked up by\nthe shipping company at the rental end date. If you cannot be\nreached, late fees will apply.\nCancelation: Orders will receive a full refund when canceled 10\nbusiness days before the rental start date.", }, }, { name: { original: "Week", translated: "Week", }, lineType: "PLAIN_TEXT", plainTextValue: { original: "3", translated: "3", }, plainText: { original: "3", translated: "3", }, }, ], physicalProperties: { shippable: true, }, paymentOption: "FULL_PAYMENT_ONLINE", quantityAvailable: 2, }, }, ], }; };
Errors

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

Did this help?

getConfig( )


Retrieves the configuration of your catalog plugin.

Set your catalog configuration in the return of the getConfig() function. Wix calls this function when you publish your site. Changes to the configuration don't take effect until you publish your site.

Currently no configurations are available for this plugin, so set getConfig() to return an empty object.

Where to find getConfig()

When you add the Catalog service plugin, a folder is automatically added to your site. Use the -config.js file in the folder to set the default configuration for your implementation of the service plugin.

For more information on setting your configuration, see Velo Tutorial: eCommerce Catalog Service Plugin.

Method Declaration
Copy
function getConfig(): Promise<CatalogConfigResponse>;
Request
This method does not take any parameters
Returns
Return Type:Promise<CatalogConfigResponse>
Example of a configuration file
JavaScript
// Place this code in the <my-extension-name>-config.js file // in the 'ecom-catalog' folder of the // Custom Extensions section on your site. export function getConfig() { return {}; }
Errors

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

Did this help?