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.
-
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 Create Cart with the following
lineItems
array in the payload to create a new cart that includes the item:Copy1The
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'soptions
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:
Copy1 -
Your implementation of Get Catalog Items returns a response like this one:
Copy1It'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.
- The
-
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.
-
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:Copy1The
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'soptions
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:
Copy1 -
Your implementation of Get Catalog Items returns a response like this one:
Copy1It'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 inoptions
. - The response must include all fields marked as required in the response description.
- The
-
Wix adds the item to the visitor's checkout, including the name, price, image, and variant details.