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:
Learn more about implementing a Wix service plugin.
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:
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.
It's important to note the following points before starting to code:
To integrate an external catalog with the Wix eCommerce platform:
To enable your Wix app to communicate with your external catalog:
Select an app from the Custom Apps page in your Wix Studio workspace.
Go to Extensions in your app's dashboard.
Click Create Extension.
Scroll down to Ecom Catalog and click Create.
In the JSON editor, assign the URI where the Catalog service plugin is implemented to deploymentUri
. For example:
{
"deploymentUri": "https://my-external-catalog.com/"
}
Note: Other fields in the JSON editor are reserved for future functionality.
Click Save.
This article explains how to handle item customization and variants when implementing the Catalog service plugin.
catalogReference
objectWhen 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.options
fieldIn 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:
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.
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:
"options": {"Size": "M", "Color": "Red"}
"options": {"customText": "Natalie"}
"options": {"recipientName": "Omar", "message": "Happy anniversary!"}
If you take this approach, make sure that:
options
properties, processes them, and returns the correct item details.options
property of the item's catalogReference
only includes key:value pairs that your catalog supports.Use this approach if:
options
object's properties in your implementation of Get Catalog Items.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:
organizationId
, campaignId
and amount
. It returns a unique donationId
.donationId
.donationId
.catalogReference
object's options
property. For example: "options": { "donationId": "bf3b953d-d0b7-4755-a54e-13c167fc4484"}
.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:
options
property of the item's catalogReference
contains a field with the item variant ID your API generated.options
object, and returns the correct item details.Use this approach if:
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.
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.
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.
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:
{
"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.
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:
{
"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"
}
Your implementation of Get Catalog Items returns a response like this one:
{
"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:
catalogReference
object in the response must be identical to the one received in the request.options
.Wix adds the item to the visitor's cart, including the name, price, image, and variant details.
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.
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.
The app code calls a custom API with the variant details. The custom API validates and stores these details, then returns a unique variantId
.
The app code calls Create Checkout with the following lineItems
array in the payload to create a new checkout that includes the item:
{
"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.
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:
{
"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"
}
Your implementation of Get Catalog Items returns a response like this one:
{
"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:
catalogReference
object in the response must be identical to the one received in the request.variantID
provided in options
.Wix adds the item to the visitor's checkout, including the name, price, image, and variant details.
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 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:
catalogReference
object. This must be identical to the catalogReference
object received in the request.data
object with full details about the item.Notes:
catalogItems
array in the response.catalogItems
must contain an empty array.Catalog reference details for the items to retrieve, including quantity of each item.
Weight measurement unit.
By default, Wix sends the weight unit specified in the site's settings.
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.
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.
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.
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"
}'
{
"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
}
}
}
]
}