Velo Tutorial: eCommerce Catalog Service Plugin (Beta)
The Service Plugins feature is currently in beta. Some service plugins are not yet available to all users.
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:
- Create a new catalog service plugin on your site.
- Implement your plugin with custom code.
- 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.
-
Add the Wix Stores app to your site.
-
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.
- Wix Studio: If necessary, click
-
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.
-
Hover over Service Plugins and click
, then click Catalog.
-
Follow the prompts to add the plugin and accept any terms and conditions that display.
-
Enter a name for your integration and click Add & Edit Code. The name can't contain spaces or special characters.
-
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.
-
Publish your site.
-
Open the Live Site Events 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>
). -
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.
Note
If you also have Wix Stores and Wix Bookings catalogs on your site, when getCatalogItems()
is called, the options
parameter only contains references to your custom catalog items. The Wix Stores and Wix Bookings catalog items are automatically returned.
Example options object:
1
Note
The value of weightUnit
is based on the regional format set on your site. To set a regional format open your site’s dashboard and go to Settings > Language & Region.
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:
1
<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:
1
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:
- Hover over the plugin folder's name and click Show More
.
- Select the New.js file.
- Hover over the plugin folder's name and click Show More
-
Wix Studio: Create a new file in the plugin's folder.
To import from these files to the main files, use the following syntax:
1
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 the Site Events log.
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.
Note: These examples and their steps are based on Wix Editor sites. You can adapt the steps for a Wix Studio site by using the equivalent Wix Studio features.
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.
Note Clicking the link to the sample site opens a copy of the site. Publishing the copy adds it to your Wix account.
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.
Note Clicking the link to the sample site opens a copy of the site. Publishing the copy adds it to your Wix account.
Limitations
The catalog service plugin is still in beta. Therefore, the following limitations apply:
catalogItems[i].data.descriptionLines
don't show up in the cart.- After adding an item to the cart, the cart might not reload. To fix this, implement the following code:
- Put
import { cart } from 'wix-stores-frontend';
at the top of the file. - Use the
cart.reload();
function to force reload the cart.
- Put