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

## Article: Introduction

## Article Link: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/catalogs/catalog-service-plugin/introduction.md

## Article Content:

# About the Wix eCommerce Catalog Service Plugin

<blockquote class="important">

__Important:__ 
When developing websites or building apps with Blocks, use [Velo service plugins](https://dev.wix.com/docs/velo/events-service-plugins/about-events-service-plugins-and-the-sdk.md).

</blockquote>

The Catalog service plugin 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](https://dev.wix.com/docs/build-apps/get-started/tutorials/tutorial-build-an-e-commerce-business-solution/overview.md) offering functionality that differs from Wix's in-house solutions like [Wix Stores](https://support.wix.com/en/article/wix-stores-about-wix-stores) or [Wix Bookings](https://support.wix.com/en/article/wix-bookings-about-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.


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

+ Create a database of items on the platform of your choice.
+ Learn how to [handle item variants](https://dev.wix.com/docs/rest/business-solutions/e-commerce/catalogs/catalog-service-plugin/handle-item-variants.md) with the Catalog service plugin.
+ Existing solutions may already provide the catalog functionality that you need. Check out [Wix Stores](https://support.wix.com/en/article/wix-stores-about-wix-stores) and [Wix Bookings](https://support.wix.com/en/article/wix-bookings-about-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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/catalogs/catalog-and-custom-items.md).
+ For an overview of the Wix eCommerce platform and its capabilities, take a look at the [Wix eCommerce Platform Handbook](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/introduction.md).
+ We are constantly updating functionality. Check the documentation regularly to see the latest capabilities. Currently, external catalog integration has a few limitations:
    + Coupons aren't yet supported.
    + Preview mode in the Wix editor doesn't reflect full functionality.
    + Integration with external sales channels isn't yet available.


::::tabs
:::REST_TAB

## Get started
To integrate an external catalog with the Wix eCommerce platform:

1. Implement the [Get Catalog Items](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/catalogs/catalog-service-plugin/get-catalog-items.md) method so Wix can retrieve the information it needs about specific items.

    >**Note:** When Wix calls your app's implementation of the Get Catalog Items method, your app receives a request containing a payload as an [encoded JWT](https://dev.wix.com/docs/build-apps/develop-your-app/access/authentication/verify-requests-received-from-wix.md).

1. Create an app in your Wix Studio workspace and [add a catalog integration extension](#configuration).


## App Configuration

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

1. Select an app from the [**Custom Apps** page](https://manage.wix.com/studio/custom-apps) in your Wix Studio workspace. 

1. Go to **Extensions** in your app's dashboard.

1. Click **Create Extension**.

1. Scroll down to **Ecom Catalog** and click **Create**.

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

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

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

1. Click **Save**.


:::
:::SDK_TAB

## Get started

Follow these steps to begin implementing your service plugin:

### Step 1 | Choose a framework

You can implement this service plugin with the following [frameworks](https://dev.wix.com/docs/build-apps/get-started/overview/wix-s-development-frameworks.md):

+ **Wix CLI:** Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md).
+ **Self-hosted:** Learn how to [implement a self-hosted service plugin with the SDK and the app dashboard](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md).

### Step 2 | Configure your service plugin

To configure and customize your plugin, you need to provide important information in the service plugin configuration file. You can [configure your plugin in the app dashboard](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-1--add-a-service-plugin-extension-to-your-app). For details, see [Catalog Extension Configuration](https://dev.wix.com/docs/rest/business-solutions/e-commerce/catalogs/catalog-service-plugin/extension-config.md).

### Step 3 | Define handler functions

Use [`catalog.provideHandlers()`](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md#step-4--define-handler-functions) to define the following handler function that implement your custom business logic.

| Function                                                                                                           | Required |
|--------------------------------------------------------------------------------------------------------------------|----------|
| [`getCatalogItems()`](https://dev.wix.com/docs/rest/business-solutions/e-commerce/catalogs/catalog-service-plugin/get-catalog-items.md) | Yes      |

## Code examples

Below is an example for implementing the Catalog service plugin in your code.

### CLI: Basic code structure

This is the basic code structure for implementing the Catalog service plugin with the Wix CLI:

```js
import { catalog } from '@wix/ecom/service-plugins'

catalog.provideHandlers({
  getCatalogItems: async (payload) => {

    const {request, metadata} = payload;

    // Add your logic here

  }
});

```

### Self-hosted: Basic code structure

This is the basic code structure for implementing a self-hosted Catalog service plugin:

```js
import { createClient } from '@wix/sdk';
import { catalog } from '@wix/ecom/service-plugins'

const wixClient = createClient({
  auth: {
    appId: <YOUR_APP_ID>,
    publicKey: <YOUR_APP_PUBLIC_KEY>
  },
  modules: { catalog }
});

wixClient.catalog.provideHandlers({
  getCatalogItems: async (payload) => {

    const { request, metadata } = payload;

    // Add your logic here

  }
});

// Implement a router to process all requests
express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});

```

:::
::::


## 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/cart/introduction.md). 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/purchase-flow/checkout/checkout/introduction.md). 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](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/introduction.md) 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.

## See also
+ [About Service Plugin Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/service-plugins/about-service-plugin-extensions.md)
+ [Add a Service Plugin Extension With the CLI](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/wix-cli/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md)
+ [Add a Self-hosted Service Plugin With the SDK](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-the-sdk.md)
+ [Add Self-hosted Service Plugin Extensions with REST](https://dev.wix.com/docs/build-apps/develop-your-app/frameworks/self-hosting/supported-extensions/backend-extensions/add-self-hosted-service-plugin-extensions-with-rest.md)