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

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 Create Cart with the following lineItems array in the payload to create a new cart that includes the item:

   Copy

   1
   
   

   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

   1
   
   

4. Your implementation of Get Catalog Items returns a response like this one:

   Copy

   1
   
   

   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

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

   1
   
   

   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

   1
   
   

5. Your implementation of Get Catalog Items returns a response like this one:

   Copy

   1
   
   

   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.