Velo Tutorial: eCommerce Catalog Service Plugin

Wix service plugins (formerly SPIs and custom extensions) allow you to implement custom logic to change how your site behaves and displays. For example, when you set up a Wix eCommerce site, there are a limited number of catalogs to choose from and some limitations on how you can define the products and services you wish to sell. To describe your product in a way that is not currently natively supported, or create a simplified catalog of services, you can use a service plugin.

Read more information on how to implement a service plugin.

This guide explains how to set up a catalog service plugin on your site using Velo.

The process has 3 steps:

1. Create a new catalog service plugin on your site.
2. Implement your plugin with custom code.
3. Deploy the plugin.

Step 1: Create a new catalog service plugin

The first step in setting up your new plugin is to add it to your site. This process creates a new folder in the Service Plugins section of the Velo sidebar (Wix Editor), or the /src/backend/spi section of the Wix IDE Explorer (Wix Studio), which contains the files for your code.

1. Add the Wix Stores app to your site.

2. Enable coding:

   • Wix Studio: If necessary, click and then Start Coding.
   • Wix Editor: Enable Velo Dev Mode, and then click the Public & Backend tab in the Velo sidebar.

3. Go to the Service Plugins section:

   • Wix Studio: Click Packages & Apps.
   • Wix Editor: Scroll down to the Service Plugins panel at the bottom of the sidebar.

4. Hover over Service Plugins and click , then click Catalog.

5. Follow the prompts to add the plugin and accept any terms and conditions that display.

6. Enter a name for your integration and click Add & Edit Code. The name can't contain spaces or special characters.

7. Wix Studio: Open the Wix IDE, and go to /src/backend/spi/ecom-catalog. If your service plugin doesn't appear, try refreshing both the Studio Editor and the Wix IDE.

8. Publish your site.

9. Open Wix Logs window and keep it open. There should be a log with the text: Your site was published with an update to the ecom catalog plugin, 'my-plugin-name' (appId: <appId-guid>).

10. Save/copy the appId you received in the log. You will need this when returning catalog items from your plugin.

Step 2: Implement the plugin

The procedure in the previous step creates a folder in the service plugins section of the Velo sidebar (Wix Editor), or in the Wix IDE's Explorer (Wix Studio). The name of the folder is based on the plugin you chose. Inside this is another folder with the name of the plugin you set up. This folder contains 2 files, <my-plugin-name>.js and <my-plugin-name>-config.js.

Implement the custom code for your plugin in these files. Below are some guidelines for writing your code. 

<my-plugin-name>.js

The code in this file defines a function named getCatalogItems(). This function is called by Wix eCommerce to retrieve the catalog items provided by your service plugin. The function accepts the following parameter:

options: An object containing catalog item references (within your own catalog), quantities, and weight unit. This data is to be used by your plugin to retrieve your catalog items. These details are requested by Wix eCommerce when, for example, an item is added to your site's cart. For more details, see the service plugin Reference.

Example options object:

The getCatalogItems() function must return an object with a key called catalogItems. The value of this key is an array of catalogReference and data objects. These objects define the catalog items' references in your catalog, as well as each item's data.

For the value of catalogReference.appId, use the appId you received in the log from Step 1.9 described above.

In the data object, productName, itemType, and price are required fields. For more details, see the service plugin reference.

Example return value:

<my-plugin-name>-config.js

The code in this file defines a function named getConfig() that returns an object containing configurations for the catalog. Currently no configurations are available.

Example return object:

Add files to the plugin

If you don't want to keep all of your code in the main files, you can add files to the plugin's folder and import functions and objects into the main files.

• Wix Editor:

  1. Hover over the plugin folder's name and click Show More .
  2. Select the New.js file.

• Wix Studio: Create a new file in the plugin's folder.

To import from these files to the main files, use the following syntax:

Test the plugin

To test your plugin, create a custom product page based on your catalog's items. Write code that calls the addToCurrentCart() function (see Limitations section below). Make sure to pass the items' catalog references in the options.lineItems.catalogReference parameter. This should be similar to the catalogReference object described above. Make sure to use your catalog's appId - see Step 1.9.

You can test your plugin before publishing your site in the Wix Editor using functional testing like you would any backend Velo code. Make sure your getCatalogItems() function's return values are properly formatted.

You can test your plugin after deploying for both Wix Editor and Wix Studio. To test your plugin after deploying, add console logs to your code. The results appear in Wix Logs.

Step 3: Deploy the plugin

Once your code files are ready, publish your site. Any catalog items you've integrated into dynamic pages are displayed on the relevant pages. When you add an item to the cart, the item details are displayed in the cart (and then later in the checkout and order flows). 

Examples

We created some examples to demonstrate how you can use service plugins to create your own custom catalog.

Poems Catalog

In this example, a simple catalog of poems has been integrated into the site. The catalog plugin uses a collection in the Content Management System (CMS) as the catalog source. The poems-catalog.js plugin file includes code that fetches catalog item info from the poems collection using the wix-data API, as well as a toCatalogItems() function that constructs the catalog item to be returned by the service plugin.

We built a sample site where you can see this code in action.

RV Rentals Catalog

In this more complex example, several collections are used together to implement an RV rental catalog. Some collections hold the RV details themselves, while others hold availability and stock data. The site includes detailed dynamic product pages that display not only product info but also availability status depending on the selected rental dates.

Have a look at the sample site where you can go through the code to see the implementation for yourself. 

Limitations

After adding an item to the cart, the cart might not refresh. To fix this, implement the following code:

• Put import wixEcomFrontend from "wix-ecom-frontend"; at the top of the file.
• Use the refreshCart(); function to force refresh the cart.