Velo Tutorial: eCommerce Catalog Custom Extension (Beta)

Wix custom extensions allow you to implement custom logic to change how your site behaves and displays using Velo SPIs. 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 supported natively, or create a simplified catalog of services, you can use a custom extension. Learn more about using Custom App Extensions Using SPIs.

Custom extensions are implemented with Velo using Wix SPIs. Learn more about custom extensions. 

This guide explains how to set up a catalog custom extension on your site using Velo.

The process has 3 steps:

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

Step 1: Create a new catalog custom extension

The first step in setting up your new extension is to add it to your site. This process creates a new folder in the Custom Extensions 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 Custom Extensions section:

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

4. Hover over Custom Extensions and click , then click Add Catalog SPI.

5. Follow the prompts to add the extension 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 Custom Extension doesn't appear, try refreshing both the Studio Editor and the Wix IDE.

8. Publish your site.

9. 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 extension, 'my-extension-name' (appId: <appId-guid>).

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

Step 2: Implement the extension

The procedure in the previous step creates a folder in the Custom Extensions 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 extension you chose. Inside this is another folder with the name of the extension you set up. This folder contains 2 files, <my-extension-name>.js and <my-extension-name>-config.js.

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

<my-extension-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 custom extension. 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 extension 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 SPI Reference.

Example options object:

1
{
2
  "catalogReferences": [
3
    {
4
      "catalogReference": {
5
        "catalogItemId": "2",
6
        "appId": "7ff4b539-e3bf-4d8e-84d4-2ed180fce336",
7
        "options": {
8
          "week": "3"
9
        }
10
      },
11
      "quantity": 1
12
    }
13
  ],
14
  "weightUnit": "LB"
15
}

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 SPI Reference.

Example return value:

1
{
2
  "catalogItems": [
3
    {
4
      "catalogReference": {
5
        "appId": "<your-catalog-appId>",
6
        "catalogItemId": "2",
7
        "options": {
8
          "week": "3"
9
        }
10
      },
11
      "data": {
12
        "productName": {
13
          "original": "EuroCamper"
14
        },
15
        "itemType": {
16
          "preset": "PHYSICAL"
17
        },
18
        "price": "540",
19
        "media": "wix:image://v1/11062b_7fba2fc327a04e1493f1a28213e8cae8~mv2.jpeg/camping-site#originWidth=6924&originHeight=3130",
20
        "descriptionLines": [
21
          {
22
            "name": {
23
              "original": "Beds"
24
            },
25
            "plainText": {
26
              "original": "Type: Double, Quantity: 1\nType: King, Quantity: 1"
27
            }
28
          },
29
          {
30
            "name": {
31
              "original": "Size"
32
            },
33
            "plainText": {
34
              "original": "7x3x3"
35
            }
36
          },
37
          {
38
            "name": {
39
              "original": "Description"
40
            },
41
            "plainText": {
42
              "original": "Professional Travelers RV for road trips, Enjoy a comfortable mobile home for the best family experience !"
43
            }
44
          },
45
          {
46
            "name": {
47
              "original": "Additional Info"
48
            },
49
            "plainText": {
50
              "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."
51
            }
52
          },
53
          {
54
            "name": {
55
              "original": "Week"
56
            },
57
            "plainText": {
58
              "original": "3"
59
            }
60
          }
61
        ],
62
        "physicalProperties": {
63
          "shippable": false
64
        },
65
        "quantityAvailable": 2
66
      }
67
    }
68
  ]
69
}

<my-extension-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
export function getConfig() {
2
  return {}
3
}

Add files to an extension

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

• Wix Editor:

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

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

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

1
import { functionName } from './myFileName.js';

Test an extension

To test your extension, 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 extension 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 extension after deploying for both Wix Editor and Wix Studio. To test your extension after deploying, add console logs to your code. The results appear in the Site Events log.

Step 3: Deploy the extension

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 custom extensions to create your own custom catalog.

Poems Catalog

In this example, a simple catalog of poems has been integrated into the site. The catalog extension uses a collection in the Content Management System (CMS) as the catalog source. The poems-catalog.js extension 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 SPI.

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

The catalog custom extension 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.