About the eCommerce Catalog Service Plugin

The Catalog service plugin (formerly SPI) lets you become a Wix catalog provider. This means you can integrate any external repository of sellable items with the Wix eCommerce platform. Wix calls the Catalog service plugin to get up-to-date information about items whenever a cart or checkout is updated, and when an item is added to an order.

With the Catalog service plugin, you can:

  • Build a comprehensive business solution offering functionality that differs from Wix's in-house solutions like Wix Stores or Wix Bookings, and integrate your solution with the Wix eCommerce platform to handle transactional capabilities. For example, develop an app to manage equipment rentals, online courses, subscriptions, or vouchers.
  • Integrate an externally managed repository of sellable items with the Wix eCommerce platform to meet specific business needs. For example, if your business handles pricing or availability in a unique way, or if you sell items that aren't easily categorized as physical or digital products or services.
  • Create a Wix app to integrate an existing eCommerce repository on a different platform with Wix's eCommerce platform.

Learn more about implementing a Wix service plugin.

Why an external catalog?

The Catalog service plugin enables you to maintain a complex and dynamic external catalog while being confident Wix can retrieve the latest information for every action.

For example, after a customer adds a particular item to their cart, one of the following details might change in your dynamic catalog:

  • The name of the item might be changed.
  • The price might be adjusted.
  • The item might go out of stock.

With the Catalog service plugin, you can be sure that when the customer moves the item from their cart to their checkout, Wix will retrieve the updated details from your catalog automatically.

Before you begin

It's important to note the following points before starting to code:

  • Existing solutions may already provide the catalog functionality that you need. Check out Wix Stores and Wix Bookings, which provide built-in catalogs. If they cater to your needs, you probably don't need to implement the Catalog service plugin.
  • For some items, you might not need an external catalog. Learn more about catalog and custom items.
  • For an overview of the Wix eCommerce platform and its capabilities, take a look at the Wix eCommerce Platform Handbook.
  • We are constantly updating functionality. Check the documentation regularly to see the latest capabilities. Currently, external catalog integration has a few limitations:
    • Coupons and subscriptions aren't yet supported.
    • Preview mode in the Wix editor doesn't reflect full functionality.
    • Integration with external sales channels isn't yet available.

Get started

To integrate an external catalog with the Wix eCommerce platform:

  1. Create a database of items on the platform of your choice.
  2. Learn how to handle item variants with the Catalog service plugin.
  3. Implement the Get Catalog Items endpoint so Wix can retrieve the information it needs about specific items.
  4. Create an app in your Wix Studio workspace and add a catalog integration extension.

App Configuration

To enable your Wix app to communicate with your external catalog:

  1. Select an app from the Custom Apps page in your Wix Studio workspace.

  2. Go to Extensions in your app's dashboard.

  3. Click Create Extension.

  4. Scroll down to Ecom Catalog and click Create.

  5. In the JSON editor, assign the URI where the Catalog service plugin is implemented to deploymentUri. For example:

    Copy
    { "deploymentUri": "https://my-external-catalog.com/" }

    Note: Other fields in the JSON editor are reserved for future functionality.

  6. Click Save.

Terminology

  • Catalog: A repository containing items for sale. Wix business solutions, such as Wix Bookings and Wix Stores, provide built-in catalogs. External business solutions can provide the Wix eCommerce platform with access to their catalogs via the Catalog service plugin. This enables robust integration of the platform’s cart and checkout functionalities with diverse business types.
  • Item: An item in a catalog can be anything sellable, including physical products, services, gift cards, pricing plans, and custom items created for individual transactions like specialized project work.
  • Cart: A customer's cart holds information about a potential transaction, including details about selected items, prices, and discounts, as well as the potential buyer. Site visitors can see their cart on the cart page. Developers can access and manage a customer's cart with the Cart API. When an item is added to a cart, Wix calls the Catalog service plugin to retrieve current details for the item.
  • Checkout: Checkout is the page where a buyer finalizes a purchase. Each checkout holds information about the items to be purchased, price and tax summaries, shipping and billing information, any applied discounts, and more. Developers can access and manage checkout details and trigger checkout-related events with the Checkout API. When an item is added to a checkout, Wix calls the Catalog service plugin to retrieve current details for the item.
  • Order: Once a customer has committed to a purchase, an order is created. An order holds information about purchased items, price and tax summaries, shipping and billing information, any applied discounts, and the status of payment and fulfillment. In the dashboard, business staff can create new orders, view and edit existing orders, track fulfillment, and manage the payments cycle. The Orders API enables apps or site owners to customize management of the order lifecycle, including viewing, editing, approving, canceling, and charging. When an item is added to an order, Wix calls the Catalog service plugin to retrieve current details for the item.
Did this help?

Handle Item Variants

This article explains how to handle item customization and variants when implementing the Catalog service plugin.

The catalogReference object

When Wix calls the Get Catalog Items endpoint, it includes a catalogReference object containing the reference details for each item to retrieve from your catalog. This object includes the following properties:

  • catalogItemId: The ID of the item in the catalog it belongs to. You can use any system you like for generating and storing unique item IDs. You may wish to expose an API so your app can query and retrieve item IDs.
  • appId: ID of the app providing the catalog. You can get your app's ID from your app's dashboard.
  • options: Additional item details in key:value pairs. Use this optional field to specify a variant of the item or add custom details. See below for more information.

The options field

In some cases, your catalog might need more than just the item ID and app ID in order to return all of the correct item details. On a site's item page, visitors can often choose variants of the item or add custom details. For example:

  • T-shirt size
  • Recipient information for a gift
  • Time and date of an appointment
  • Donation or gift card amount
  • Custom text for a necklace

There are several ways you can use the options object for handling item variants. Here are two different approaches to implementing it. Decide which approach to take based on your technical requirements, existing system architecture, and business needs.

Approach 1 | Pass variant details in options

You can pass specific information about the item in the options object as key:value pairs. You can choose how to structure the information and what keys and values to support.

For example, you can specify item variant details in any of the following ways:

  • T-shirt size and color: "options": {"Size": "M", "Color": "Red"}
  • Custom text for a necklace: "options": {"customText": "Natalie"}
  • Recipient information: "options": {"recipientName": "Omar", "message": "Happy anniversary!"}

If you take this approach, make sure that:

  • Your Catalog service plugin implementation handles the expected options properties, processes them, and returns the correct item details.
  • When your app adds an item to a cart, checkout, or order, the options property of the item's catalogReference only includes key:value pairs that your catalog supports.

Use this approach if:

  • You prefer not to store details for every variant a client selects, unless they result in a purchase.
  • You don't mind handling validation of the options object's properties in your implementation of Get Catalog Items.

Approach 2 | Pass a variant ID in options

You can create a separate API that processes item variants and returns a unique variant ID. Then your app can pass an options object containing only the item variant ID. When Wix calls Get Catalog Items, your Catalog service plugin retrieves the correct details for the item variant on the basis of this ID and returns them.

For example, suppose you are creating an app for processing donations that can be added to a customer's transaction. You could implement this as follows:

  1. Create an API called Create Donation for generating the specific details for a given donation. The request body might include properties that vary between donations, such as organizationId, campaignId and amount. It returns a unique donationId.
  2. Create an API called Get Donation for retrieving the details of a donation based on its unique donationId.
  3. When a site visitor makes a donation, they specify their preferred organization, campaign, and donation amount. The app then sends these details to the Create Donation API, which creates a donation entry and stores the details in your catalog's database. It then returns a unique donationId.
  4. When your app adds a donation to a cart, checkout, or order, include the unique donation ID in the catalogReference object's options property. For example: "options": { "donationId": "bf3b953d-d0b7-4755-a54e-13c167fc4484"}.
  5. When Wix calls your Get Catalog Items endpoint to retrieve current information on the donation, it provides the catalogReference for the item, including the unique donationId. On the basis of this ID, the endpoint returns the full details for the specific donation, which can then be added to the cart, checkout, or order.

If you take this approach, make sure that:

  • You implement an API for creating item variants. Your API must receive the required variant details, store them, and generate a unique ID for each item variant.
  • When your app adds an item to a cart, checkout, or order, the options property of the item's catalogReference contains a field with the item variant ID your API generated.
  • Your Catalog service plugin implementation expects and handles the unique item variant IDs it receives in the options object, and returns the correct item details.

Use this approach if:

  • You don't mind storing details for every variant a client selects, including those that don't result in a purchase.
  • You prefer to implement a formal API that enforces structure and validates all variants before they are included in a request to the catalog.
Did this help?

Catalog Service Provider: Sample Use Cases & Flows

This article presents sample flows your app can support. You aren't limited to this exact flow, but it can be a helpful jumping off point as you plan your catalog integration.

Add a catalog item to a cart

Note: In this example, item variant details are passed in the request. Learn more about this approach to handling item variants.

In this flow, a site visitor adds an item to their cart. Wix calls the Catalog service plugin to retrieve the item's full details. Before implementing this flow, configure your app, so it can communicate with your Catalog service plugin implementation.

  1. A site visitor selects a color and size for a customizable T-shirt on a Wix site's item page. Then they add it to their cart.

  2. The app code calls Add To Current Cart with the following lineItems array in the payload to create a new cart that includes the item:

    Copy
    { "lineItems": [ { "quantity": 1, "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } } } ] }

    The catalogReference object for the item includes:

    • appId: The ID of the app the catalog belongs to. This tells Wix which app's implementation of the Catalog service plugin to call.
    • catalogItemId: The ID of the item in the catalog it belongs to.
    • options: Item variant information.

    In this case, the app handles item variants by passing the variant details in the catalogReference object's options field.

  3. Wix automatically calls your app's implementation of Get Catalog Items with the following payload as an encoded JWT to retrieve the item's full and current details:

    Copy
    { "catalogReferences": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } }, "quantity": 1 } ], "currency": "USD", "weightUnit": "KG" }
  4. Your implementation of Get Catalog Items returns a response like this one:

    Copy
    { "catalogItems": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } }, "data": { "productName": { "original": "Cotton T-shirt" }, "url": { "relativePath": "/product-page/t-shirt", "url": "https://www.<MY_STORE>.com/" }, "itemType": { "preset": "PHYSICAL" }, "price": { "amount": "80.00" }, "descriptionLines": [ { "name": { "original": "Size", "translated": "Size" }, "plainText": { "original": "Medium", "translated": "Medium" } }, { "name": { "original": "Color", "translated": "Color" }, "plainText": { "original": "Green", "translated": "Green" } } ], "physicalProperties": { "sku": "889809004958", "shippable": true }, "media": { "id": "3258d9_77f175cc4d234714825fbf316803ca9a~mv2.png", "height": 720, "width": 720 } } } ] }

    It's important to note the following about the response:

    • The catalogReference object in the response must be identical to the one received in the request.
    • The response must include the variant details associated with the preferences specified in options.
    • The response must include all fields marked as required in the response description.
  5. Wix adds the item to the visitor's cart, including the name, price, image, and variant details.

Add a catalog item to a checkout

Note: In this example, item variant details are processed externally via a custom API that returns a unique ID. Learn more about this approach to handling item variants.

In this flow, a site visitor adds an item to their checkout. Wix calls the Catalog service plugin to retrieve the item's full details. Before implementing this flow, configure your app, so it can communicate with your Catalog service plugin implementation.

  1. A site visitor selects a color and size for a customizable T-shirt on a Wix site's item page. Then they click Buy Now to add it directly to their checkout.

  2. The app code calls a custom API with the variant details. The custom API validates and stores these details, then returns a unique variantId.

  3. The app code calls Create Checkout with the following lineItems array in the payload to create a new checkout that includes the item:

    Copy
    { "lineItems": [ { "quantity": 1, "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "variantId": "c1988f6b-00a6-4e24-bd60-ce3054a54fbd" } } } ] }

    The catalogReference object for the item includes:

    • appId: The ID of the app the catalog belongs to. This tells Wix which app's implementation of the Catalog SPI to call.
    • catalogItemId: The ID of the item in the catalog it belongs to.
    • options: Item variant information.

    In this case, the app handles item variants by using a custom API to generate and store the variant details. It then passes only the variant ID details in the catalogReference object's options field.

  4. Wix automatically calls your app's implementation of Get Catalog Items with the following payload as an encoded JWT to retrieve the item's full and current details:

    Copy
    { "catalogReferences": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "variantId": "c1988f6b-00a6-4e24-bd60-ce3054a54fbd" } }, "quantity": 1 } ], "currency": "USD", "weightUnit": "KG" }
  5. Your implementation of Get Catalog Items returns a response like this one:

    Copy
    { "catalogItems": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } }, "data": { "productName": { "original": "Cotton T-shirt" }, "url": { "relativePath": "/product-page/t-shirt", "url": "https://www.<MY_STORE>.com/" }, "itemType": { "preset": "PHYSICAL" }, "price": { "amount": "80.00" }, "descriptionLines": [ { "name": { "original": "Size", "translated": "Size" }, "plainText": { "original": "Medium", "translated": "Medium" } }, { "name": { "original": "Color", "translated": "Color" }, "plainText": { "original": "Green", "translated": "Green" } } ], "physicalProperties": { "sku": "889809004958", "shippable": true }, "media": { "id": "3258d9_77f175cc4d234714825fbf316803ca9a~mv2.png", "height": 720, "width": 720 } } } ] }

    It's important to note the following about the response:

    • The catalogReference object in the response must be identical to the one received in the request.
    • The response should include the variant details associated with the variantID provided in options.
    • The response must include all fields marked as required in the response description.
  6. Wix adds the item to the visitor's checkout, including the name, price, image, and variant details.

Did this help?

POST

Get Catalog Items


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves data for specified items in a specified catalog.

Wix calls this method whenever a cart or checkout is updated, and when an item is added to an order.

The method receives a catalogReferences array. Each catalog reference in the array contains:

  • The ID of the item whose latest information Wix needs to retrieve.
  • The ID of the app providing the catalog containing the item.
  • Optional details about preferences or customization of the item.

The method also receives preferences for the currency and weight unit to be used in the response.

Your external catalog can store and organize item details in any way you prefer. When implementing the Catalog service plugin, learn how to handle item variants in a way that meets your needs.

The method's response must contain a catalogItems array. Each item in the array must contain:

  • A catalogReference object. This must be identical to the catalogReference object received in the request.
  • A data object with full details about the item.

Notes:

  • If an item doesn't exist in the catalog, the response must exclude it from the catalogItems array in the response.
  • When none of the items requested exist in the catalog, catalogItems must contain an empty array.
  • Wix calls the method every time a cart or checkout is updated. If the response doesn't include an item that was already in the cart or checkout, Wix removes the item from the cart or checkout.
  • Learn more about implementing a Wix service plugin.
Endpoint
POST
{DEPLOYMENT-URI}/get-catalog-items
Body Params
catalogReferencesArray <CatalogReferenceAndQuantity>minItems 1maxItems 300

Catalog reference details for the items to retrieve, including quantity of each item.


weightUnitstring

Weight measurement unit.

By default, Wix sends the weight unit specified in the site's settings.


currencystringformat CURRENCY

Currency to return item prices in, in ISO 4217 format. For example, USD or EUR.

By default, Wix sends the currency specified in the site's settings.

Response Object
catalogItemsArray <Item>

Details for each item, including catalog reference details and item data. Any items that don't exist in the catalog are excluded. If none of the requested items exist in the catalog, this array must be empty.

Get Catalog Items - decoded JWT

The data payload will include the following object as an encoded JWT. For the purposes of this example, we show the request and response objects decoded.

Request
cURL
curl -X POST https://provider.example.com/get-catalog-items \ -H 'user-agent: Wix' \ -H 'accept-encoding: gzip, deflate' \ -H 'content-type: text/plain; charset=utf-8' \ -d '{ "catalogReferences": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "205c539b-fd89-4b0c-8d7e-55630f66e5f9" }, "quantity": 1 }, { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } }, "quantity": 1 } ], "weightUnit": "KG", "currency": "USD" }'
Response
JSON
{ "catalogItems": [ { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "205c539b-fd89-4b0c-8d7e-55630f66e5f9" }, "data": { "productName": { "original": "Simple Black Sun Hat" }, "url": { "relativePath": "/product-page/sun-hat", "url": "https://www.<MY_STORE>.com/" }, "itemType": { "preset": "PHYSICAL" }, "price": "20.00", "physicalProperties": { "sku": "227220141836", "shippable": true }, "media": { "id": "e3bc27_6edeb786f2aa44b19d9abcb4d1f6bfd6~mv2.png", "height": 720, "width": 720 } } }, { "catalogReference": { "appId": "3b8658a6-3282-4b5e-ae0e-439113e20aef", "catalogItemId": "f95bd723-ea83-40f2-8cb8-accff2d54866", "options": { "color": "Green", "size": "M" } }, "data": { "productName": { "original": "Cotton T-shirt" }, "url": { "relativePath": "/product-page/t-shirt", "url": "https://www.<MY_STORE>.com/" }, "itemType": { "preset": "PHYSICAL" }, "price": { "amount": "80.00" }, "descriptionLines": [ { "name": { "original": "Size", "translated": "Size" }, "plainText": { "original": "Medium", "translated": "Medium" } }, { "name": { "original": "Color", "translated": "Color" }, "plainText": { "original": "Green", "translated": "Green" } } ], "physicalProperties": { "sku": "889809004958", "shippable": true }, "media": { "id": "3258d9_77f175cc4d234714825fbf316803ca9a~mv2.png", "height": 720, "width": 720 } } } ] }
Did this help?