> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: eCommerce Catalog Service Plugin

## Article: eCommerce Catalog Custom Extension (Beta)

## Article Link: https://dev.wix.com/docs/develop-websites/articles/code-tutorials/wix-e-commerce-stores/e-commerce-catalog-service-plugin.md

## Article Content:

# 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](https://dev.wix.com/docs/develop-websites/articles/coding-with-velo/integrations/service-plugins-formerly-spis/about-service-plugins.md).

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](https://support.wix.com/en/article/wix-stores-adding-wix-stores) to your site.
2.  Enable coding:
    + **Wix Studio:** If necessary, click ![Code icon](https://github.com/wix-incubator/wix-code-docs/assets/50321691/2c41d3df-930f-4e0f-966f-038742adceed) and then **Start Coding**.  
    + **Wix Editor:** Enable [Velo Dev Mode](https://support.wix.com/en/article/about-velo-by-wix#to-enable-velo-on-your-site), and then click the **Public & Backend**  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/76096845-8b12-44f1-91f6-3dc2e838fdd9/2022/08/29/23d50509-633d-4616-9f56-65add8fa6d0b/d910e041-d150-4f35-aa75-30ad262abc7a.png)  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  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/11fda387-da5a-430a-ada3-46def885b67f/2022/03/02/65d645bd-dee9-40dc-9f91-c44b06d72492/289e91de-47c5-429c-b61d-67bd8d4fd1ec.png) , 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](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/developer-tools/logs/about-logs.md) 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](https://www.wix.com/velo/reference/spis/wix-ecom/ecom-catalog/introduction).

>**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:

```json
{
  "catalogReferences": [
    {
      "catalogReference": {
        "catalogItemId": "2",
        "appId": "7ff4b539-e3bf-4d8e-84d4-2ed180fce336",
        "options": {
          "week": "3"
        }
      },
      "quantity": 1
    }
  ],
  "weightUnit": "LB"
}
```

>**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](https://www.wix.com/my-account/site-selector/?buttonText=Go%20to%20Dashboard&title=Select%20a%20Site&autoSelectOnSingleSite=true&actionUrl=https://www.wix.com/dashboard/%7B%7BmetaSiteId%7D%7D/home/) 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](#step-1-create-a-new-catalog-custom-extension) described above.

In the `data` object, `productName`, `itemType`, and `price` are required fields. For more details, see the [service plugin reference](https://www.wix.com/velo/reference/spis/wix-ecom/ecom-catalog/getcatalogitems).

Example return value:

```json
{
  "catalogItems": [
    {
      "catalogReference": {
        "appId": "<your-catalog-appId>",
        "catalogItemId": "2",
        "options": {
          "week": "3"
        }
      },
      "data": {
        "productName": {
          "original": "EuroCamper"
        },
        "itemType": {
          "preset": "PHYSICAL"
        },
        "price": "540",
        "media": "wix:image://v1/11062b_7fba2fc327a04e1493f1a28213e8cae8~mv2.jpeg/camping-site#originWidth=6924&originHeight=3130",
        "descriptionLines": [
          {
            "name": {
              "original": "Beds"
            },
            "plainText": {
              "original": "Type: Double, Quantity: 1\nType: King, Quantity: 1"
            }
          },
          {
            "name": {
              "original": "Size"
            },
            "plainText": {
              "original": "7x3x3"
            }
          },
          {
            "name": {
              "original": "Description"
            },
            "plainText": {
              "original": "Professional Travelers RV for road trips, Enjoy a comfortable mobile home for the best family experience !"
            }
          },
          {
            "name": {
              "original": "Additional Info"
            },
            "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."
            }
          },
          {
            "name": {
              "original": "Week"
            },
            "plainText": {
              "original": "3"
            }
          }
        ],
        "physicalProperties": {
          "shippable": false
        },
        "quantityAvailable": 2
      }
    }
  ]
}
```

### `<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:

```json
export function getConfig() {
  return {}
}
```

### 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**  ![](https://d2x3xhvgiqkx42.cloudfront.net/12345678-1234-1234-1234-1234567890ab/76096845-8b12-44f1-91f6-3dc2e838fdd9/2022/09/04/45269098-373f-4d2c-8168-2fc5242c6024/c890c6a3-6762-4501-bdb4-e44c678108df.png) .
  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:

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

### Test the plugin

To test your plugin, create a custom product page based on your catalog's items. Write code that calls the [`addToCurrentCart()`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-backend/current-cart/add-to-current-cart.md) function (see [Limitations](#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](#my-integration-namejs). Make sure to use your catalog's `appId` - see [Step 1.9](#step-1-create-a-new-custom-catalog-extension).

You can test your plugin before publishing your site in the Wix Editor using [functional testing](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/testing-monitoring/functional-testing/test-backend-functions-with-functional-testing.md) 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](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/developer-tools/logs/about-logs.md).

## 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. If you'd prefer to use Wix Studio, learn more about [working with the code panel in Wix Studio](https://dev.wix.com/docs/develop-websites/articles/workspace-tools/velo-workspace/workspaces/wix-studio-working-with-the-code-panel.md).

### 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)](https://support.wix.com/en/article/content-manager-creating-a-collection) 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](https://www.wix.com/velo/reference/wix-data), as well as a `toCatalogItems()` function that constructs the catalog item to be returned by the service plugin.

We built a [sample site](https://editor.wix.com/html/editor/web/renderer/new?siteId=95d384b1-0f26-41fc-b8f2-08fb873d9b73&metaSiteId=0e57ff6f-b239-4b1c-aa20-891c6f8c6bf5) 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](https://editor.wix.com/html/editor/web/renderer/new?siteId=38fa7176-950b-46a2-a82c-50563d81e23b&metaSiteId=0ffe1191-0cf6-4927-98bd-c2ed3e338d51) 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

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();`](https://dev.wix.com/docs/velo/api-reference/wix-ecom-frontend/refresh-cart.md) function to force refresh the cart.