About Catalog and Custom Items

In the Wix eCommerce platform, flexibility in handling different item types is essential for meeting various business needs. Whether items are managed in a catalog or processed on the fly, there are several ways to handle them in the ecosystem, each with unique strengths suited to different use cases.

Item types

The following table summarizes the capabilities and advantages of each main item type:

Option	Description	Example use case	Catalog dependency
Catalog item	Full integration with catalog provider. Ensures real-time updating of item details.	Equipment rental business solution app	Catalog service plugin
Catalog item with overrides	A flexible solution for catalog-based items needing occasional customization.	Staff discount	Catalog service plugin
Custom item without catalog reference	Fully customizable. For items that don’t require real-time updates, inventory tracking, or catalog-based management.	Donations app	None
Custom item with catalog reference	Gives custom items a lightweight reference system, enabling external apps to personalize and track them effectively.	Greeting card app with custom text	External only

Each option is designed for different levels of integration with an external service and control over item details. Let's dive into the details of each type.

Catalog item

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.

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 retrieves up-to-date details from your catalog automatically.

When to use it

Implement the Catalog service plugin if you are developing a business solution like Wix Stores or Wix Bookings that relies on real-time updates for item details, availability, and pricing. Implementing the Catalog service plugin involves configuring an API endpoint and maintaining catalog synchronization.

When you add a catalog item to a Wix eCommerce flow, you provide the catalog reference, which Wix uses when calling the Catalog service plugin to retrieve the item's full details.

Example use cases

You might implement a catalog integration for:

• An equipment rental app.
• An app for selling online courses.

These are fully-fledged eCommerce apps that Wix users can install on their site to run their business.

Get started

To implement a catalog integration, you’ll first need to set up a Catalog service plugin and connect it to your external repository. To learn how to do this, see the Catalog service plugin documentation.

Then, process an item from the catalog. Follow this example flow to understand how processing a catalog item works, noting that not all steps may be necessary in your implementation:

1. Make sure you know the catalog reference details for the item you want to process.

2. Call a method that introduces a new item into the eCommerce flow. For example, this might be Add to Cart, Add to Current Cart, or Add to Checkout, depending on your needs. Include the catalog reference and desired quantity for the item you want to process in the lineItems array in the request.

3. Call a method that returns items in the eCommerce flow, such as Get Cart, Get Current Cart, or Get Checkout. The lineItems array in the response includes the item you added, with all of its up-to-date details.

   The lineItems array can contain both catalog items and custom items. For a catalog item, the customLineItem property is false.

Catalog item with overrides

This option is useful primarily for working with items from a catalog associated with a different Wix app. Sometimes you need to modify certain fields for a catalog item without breaking its connection to the catalog. This option allows you to override specific fields, such as price, while retaining catalog-based item tracking and updates for other fields.

To override catalog item fields, your app must have the permission scope named "Manage eCommerce - Admin Permissions". Learn more about permission scopes.

When to use it

Use a catalog item with overrides to enable your app to override specific items in a catalog managed by another app, like Wix Stores or Wix Bookings.

Example use cases

You might use catalog items with overrides in:

• A B2B app offering customized pricing for different groups of customers.
• An app that allows staff to offer discounts.
• A product customization app that overrides an item's title, image, or price based on preferences selected by the customer.

In these cases, the app fetches up-to-date data for the item from its catalog but overrides the price for eligible customers.

Get started

Follow this example flow to understand how processing a catalog item with overrides works, noting that not all steps may be necessary in your implementation:

1. Make sure you know the catalogReference details for the item you want to process.

2. Call a method that introduces a new item into the eCommerce flow. For example, this might be Add to Cart, Add to Current Cart, or Add to Checkout, depending on your needs. Include the catalog reference and desired quantity for the item you want to process in the lineItems array in the request.

   In addition, pass a catalogOverrideFields object containing a specified value for each field you want to override. For syntax and a list of fields that can be overridden, see the method documentation. For example, this API call adds a catalog item to the current site visitor's cart while manually overriding the price:

   Copy

   After this, the overridden value persists for the rest of the eCommerce flow.

3. Call a method that returns items, such as Get Cart, Get Current Cart, or Get Checkout. The lineItems array in the response includes the item you added with all of its up-to-date details, with values overridden for the fields you specified. In addition, the item object contains the same catalogOverrideFields field passed originally, which you can use to check which fields' values have been overridden.

   The lineItems array can contain both catalog items and custom items. For a catalog item with overrides, the customLineItem property is false.

Custom item without catalog reference

A custom item works similarly to a catalog item, except that for a custom item, Wix doesn't make calls to an external Catalog service plugin to update item details after the item is introduced to the flow. This means that when you add a custom item to an eCommerce flow, for example by adding it to a cart or checkout, the details you provide for the item persist throughout the flow exactly as you provided them.

To access and manage custom line items, your app must have the permission scope named "Manage eCommerce - Admin Permissions". Learn more about permission scopes.

When to use it

Custom items save you the effort of implementing a catalog, but they don't provide functionality for dynamic updating of item information as the eCommerce flow proceeds. So you should use custom items for one-off, purpose-specific, non-physical, or unlimited items for which you don't need inventory tracking or real-time dynamic item updates.

Example use cases

You might use custom items for:

• A donations app that allows site visitors to contribute custom amounts to a cause.
• An app for adding gift wrapping services to purchases.

Get started

Follow this example flow to understand how processing a custom item works, noting that not all steps may be necessary in your implementation:

1. Call a method that introduces a new item into the eCommerce flow. For example, this might be Add to Cart, Add to Current Cart, or Add to Checkout, depending on your needs.

   When you add a custom item to an eCommerce flow, you need to provide all of the item details, rather than just a catalog reference. Provide these details in the customLineItems array in the request.

2. Call a method that returns items, such as Get Cart, Get Current Cart, or Get Checkout. The lineItems array in the response includes the item you added with the details you provided.

   The lineItems array can contain both catalog items and custom items. For a custom item, the customLineItem property is true.

Custom item with catalog reference

Custom items can optionally include a catalogReference object like the one used in catalog items. For custom items, Wix doesn’t call an external catalog to update item details, but the catalog reference object persists throughout the eCommerce flow. This means your app can use it to store information that remains associated with the item.

This catalog reference can serve as a lightweight reference for custom items, for example when you need to record tailored item details, store a personalized message, or retain attribution details. You can also use it to associate fulfillment-related details with an item or to easily enable order queries for specific items belonging to your app.

You can either store these custom item details in the catalog reference itself, or store an ID in the catalog reference which you associate with the specific item in an external service.

To access and manage custom line items, your app must have the permission scope named "Manage eCommerce - Admin Permissions". Learn more about permission scopes.

When to use it

Use custom items with a catalog reference when you:

• Want to take advantage of the flexibility of custom items.
• Don't need dynamic updating of item details.
• Need some kind of information to be associated with an individual item as it proceeds through the Wix eCommerce flow.

Example use cases

You might use custom items with a catalog reference for:

• A greeting card app that allows customers to provide custom greeting text.
• An app for custom-made jewelry that lets customers choose various features of the jewelry item before it's made.

Get started

Follow this example flow to understand how processing a custom item with a catalog reference works, noting that not all steps may be necessary in your implementation:

1. Call a method that introduces a new item into the eCommerce flow. For example, this might be Add to Cart, Add to Current Cart, or Add to Checkout, depending on your needs.

   When you add a custom item to an eCommerce flow, you need to provide all of the item details, rather than just a catalog reference. Provide these details in the customLineItems array in the request.

   To include a catalog reference for a custom item, provide the optional catalogReference object.

   Include your item variant details in catalogReference.options, which you can structure however you like. For example:

   Copy

   Alternatively, include an ID for the item variant in catalogReference.options and associate that ID with the item details in an external service. For example:

   Copy

   Whichever approach you take, this information persists with the item and can be retrieved with other item details during later stages of the eCommerce flow.

2. Call a method that returns items, such as Get Cart, Get Current Cart, or Get Checkout. The lineItems array in the response includes the item you added with the details you provided, including the details you included in the catalogReference property.

   The lineItems array can contain both catalog items and custom items. For a custom item with a catalog reference, the customLineItem property is true.

See also

• Catalog service plugin
• Wix app developers: Build a feature app that extends eCommerce functionality
• Wix app developers: Build a new eCommerce business solution