> 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/suppliers-hub/marketplace-provider-service-plugin/introduction.md

## Article Content:

# Marketplace Provider Service Plugin

The Marketplace Provider service plugin allows third-party supplier and fulfillment platforms to integrate their product catalogs with Wix Stores. When a Wix site owner imports products from a marketplace provider, Wix calls your service plugin to retrieve product details, generate product mockup images, check real-time inventory levels, and optionally surface a pricing breakdown.

## Terminology

| Term | Description |
|------|-------------|
| Marketplace provider | A third-party supplier or fulfillment platform (such as Printful or Modalyst) that provides products to Wix site owners. |
| Product reference | A link between a product in the provider's system and a product in a Wix site's store. Contains the provider's product ID and optional provider-specific data. |
| Mockup | A composite product preview image that shows the site owner's logo or custom image on a provider's product. For example, a t-shirt with the site's logo printed on it. |
| Choice | A product variant option such as size, color, or material. Each choice has a name (for example, "Size") and a value (for example, "M"). |

## How This Service Plugin Works

Wix calls your service plugin implementation when a site owner interacts with marketplace provider products in the Suppliers Hub or their store. Wix calls [Bulk Add Products To Store](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-add-products-to-store.md) when the site owner selects products to import, [Bulk Generate Mockups](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-generate-mockups.md) when they request mockup previews, [Get Inventory](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-inventory.md) when they open a product's details page, and [Get Pricing Breakdown](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-pricing-breakdown.md) when they view pricing details in the Suppliers Hub Marketplace.

Wix calls [Bulk Add Products To Store](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-add-products-to-store.md) to create products in the site's Wix Stores catalog. For [Bulk Generate Mockups](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-generate-mockups.md), the call is asynchronous — your implementation acknowledges the request, then delivers the generated mockup images by calling [Submit Generated Mockups](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-submissions/submit-generated-mockups.md) on the [Marketplace Provider Submissions API](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-submissions/introduction.md). For [Get Inventory](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-inventory.md), Wix displays the returned stock levels on the product details page. For [Get Pricing Breakdown](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-pricing-breakdown.md), Wix displays the returned base cost, suggested retail price, potential profit, and markup rate to help the site owner decide whether to import the product.

[Get Pricing Breakdown](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-pricing-breakdown.md) is opt-in. Wix only calls it when your provider config sets `toggleGetPricingBreakdownEnabled` to `true`. Otherwise, Wix skips the call and the Suppliers Hub UI omits the pricing breakdown.

### Notifying Wix

Your service plugin can notify Wix when mockup generation is complete by calling these methods:

- [Submit Generated Mockups](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-submissions/submit-generated-mockups.md) - Call when your service has finished generating mockup images for a previous [Bulk Generate Mockups](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-generate-mockups.md) request.

::::TABS

:::REST_TAB

## Get started

To enable Wix to communicate with your app:

1. Go to [Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions.md) in your app's dashboard.
1. Click **Create Extension** in the top right.
1. Filter by **Suppliers Hub** in the left menu, then find **Marketplace Provider** and click **Create**.
1. Provide the following configuration in the JSON editor and then click **Save**.

    | Name | Type | Description |
    | --- | --- | --- |
    | `deploymentUri`|string|**Required.** Base URI where your service plugin endpoints are deployed. Wix appends the endpoint path to this base URI. For example, to reach the Bulk Add Products To Store endpoint at `https://my-provider.com/v2/bulk/add-products-to-store`, provide `https://my-provider.com/` as the base URI. |
    | `toggleGetPricingBreakdownEnabled`|boolean|Whether your implementation supports the Get Pricing Breakdown method. When `false`, Wix doesn't call your implementation for pricing breakdowns and the Suppliers Hub UI omits that section. Default: `false`. |

:::
:::SDK_TAB

## Get started

**Self-hosted implementations:**

To enable Wix to communicate with your app:

1. Go to [Extensions](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/about-extensions.md) in your app's dashboard.
1. Click **Create Extension** in the top right.
1. Filter by **Suppliers Hub** in the left menu, then find **Marketplace Provider** and click **Create**.
1. Provide the following configuration in the JSON editor and then click **Save**.

    | Name | Type | Description |
    | --- | --- | --- |
    | `deploymentUri`|string|**Required.** Base URI where your service plugin endpoints are deployed. Wix appends the endpoint path to this base URI. For example, to reach the Bulk Add Products To Store endpoint at `https://my-provider.com/v2/bulk/add-products-to-store`, provide `https://my-provider.com/` as the base URI. |
    | `toggleGetPricingBreakdownEnabled`|boolean|Whether your implementation supports the Get Pricing Breakdown method. When `false`, Wix doesn't call your implementation for pricing breakdowns and the Suppliers Hub UI omits that section. Default: `false`. |

Define handler functions using [`marketplaceProvider.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):

| Function                    | Required       |
|-----------------------------|----------------|
| [`bulkAddProductsToStore()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-add-products-to-store.md)    | Yes     |
| [`bulkGenerateMockups()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-generate-mockups.md)    | Yes     |
| [`getInventory()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-inventory.md)    | Yes     |
| [`getPricingBreakdown()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-pricing-breakdown.md)    | No (only if `toggleGetPricingBreakdownEnabled` is `true`)     |

### Self-hosted: Basic code structure

```js
import { createClient } from '@wix/sdk';
import { marketplaceProvider } from '@wix/suppliers-hub/service-plugins'

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

wixClient.marketplaceProvider.provideHandlers({
  bulkAddProductsToStore: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  },
  bulkGenerateMockups: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  },
  getInventory: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  },
  // Optional: implement only if you set toggleGetPricingBreakdownEnabled to true
  getPricingBreakdown: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  }
});

express.post('/plugins-and-webhooks/*', (req, res) => {
  wixClient.process(req);
});
```

**CLI implementations:**

Learn how to [implement a service plugin with the CLI and the SDK](https://dev.wix.com/docs/wix-cli/legacy-clis/legacy-wix-cli-for-apps/supported-extensions/backend-extensions/service-plugins/add-service-plugin-extensions-with-the-cli.md).

Define handler functions using [`marketplaceProvider.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):

| Function                    | Required       |
|-----------------------------|----------------|
| [`bulkAddProductsToStore()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-add-products-to-store.md)    | Yes     |
| [`bulkGenerateMockups()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-generate-mockups.md)    | Yes     |
| [`getInventory()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-inventory.md)    | Yes     |
| [`getPricingBreakdown()`](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/get-pricing-breakdown.md)    | No (only if `toggleGetPricingBreakdownEnabled` is `true`)     |

### CLI: Basic code structure

```js
import { marketplaceProvider } from '@wix/suppliers-hub/service-plugins'

marketplaceProvider.provideHandlers({
  bulkAddProductsToStore: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  },
  bulkGenerateMockups: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  },
  getInventory: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  },
  // Optional: implement only if you set toggleGetPricingBreakdownEnabled to true
  getPricingBreakdown: async (payload) => {
    const { request, metadata } = payload;
    // Add your logic here
  }
});
```

:::
::::

## Requirements and constraints

Your service plugin implementation must meet the following requirements:

- Respond within 10 seconds for all methods. Longer response times result in timeout errors.
- Maintain high availability (99.9% uptime recommended). Downtime affects all Wix sites using your implementation.
- Handle timeouts gracefully. If your implementation doesn't respond within the timeout window, Wix falls back to default behavior and logs the timeout event.

### Error handling

Your service plugin implementation must support returning defined errors when appropriate conditions occur. Implement proper error handling to ensure Wix can respond appropriately to different failure scenarios.

The [Bulk Generate Mockups](https://dev.wix.com/docs/api-reference/business-solutions/suppliers-hub/marketplace-provider-service-plugin/bulk-generate-mockups.md) method defines specific error codes for cases where a product doesn't support mockup generation or the provided image isn't supported. Return these errors with the appropriate error code so Wix can display a helpful message to the site owner.