The supplemental catalog is a feed designed to store price and availability attributes for items across different stores or sales channels. It cannot operate as a standalone item feed and must be used alongside a main item feed that contains the complete item information. In this setup, the main item feed does not need to include price or availability data, as these will be sourced from the supplemental catalog. The supplemental catalog obtains its data from a catalog created and populated in

**Data Modeling Hub > Catalogs** - this is the first step in implementing a supplemental catalog. Then, you create a supplemental catalog feed based on this catalog and link it to your chosen main item feed(s). For detailed instructions, see the ["Implementing supplemental catalogs" section](#implementing-supplemental-catalogs). ### Business benefits - Manage prices and availability individually for each store or sales channel. - Achieve better organization of attributes in recommendation filters. ### Purpose and usage - Must contain the `price` and `availability` item attributes, but can include additional attributes as well. - When connected with the main item feed: - The **main item feed** includes common item attributes. - The **supplemental catalog** holds item prices and availability per store or sales channel. - When supplemental catalog or catalogs are connected with the item feed, the supplemental attributes are available for use in: - the [recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters):

Highlighted tab contains supplemental attributes from the supplemental catalogs connected to the item feed in the filter visual builder

- the [recommendation preview](/docs/ai-hub/recommendations-v2/previewing-recommendations#previewing-recommendation-supplemental-catalog-context) (only `channel` attribute from the catalog):

A dropdown menu that allows you to select a supplemental catalog, enabling filtering of recommended items based on the channels defined within that catalog

### Requirements - The file imported into a catalog must include the following attributes:

| Attribute | Description | Value type | |-------------|------------------------------------------------------|------------| | `itemId` | Unique identifier of the item. | string | `channelId` | Identifier of a store or sales channel. | a string that matches this regular expression: `^[-_a-zA-Z0-9:]+$` | | `price.value` | A price of an item in a store or sales channel | float | | `availability` | Availability of an item in a store / sales channel | boolean | **Example**:

channelId,itemId,availability,price.value
  store100,Xa34ad3d,true,29.99
  store101,Xa34ad3d,true,25.99
  store102,Xa34ad3d,true,27.99
  store103,Xa34ad3d,false,28.99

- The `itemKey` must be an item ID (this information is important for importing JSON file to a catalog through API). - The file must contain the following parameters and objects: - The `itemId` parameter must be a string. - The `availability` parameter must be a boolean. - The `channelId` parameter must be a string. - The `price` object must be a float. **Example**:

{
    "itemId": "59067514940593",
    "availability": true,
    "channelId": "europeRegion",
    "price": {
      "value": "12.99"
    }
  }

Regardless of the file type you import to a catalog (either through a simple import or through a workflow), you must enable the **JSON dot notation** toggle.

Selection of the catalog

- The required file format depends on the method you will choose to upload data to a catalog: - for a [simple import](/docs/assets/imports/importing-data-to-catalogs) - only CSV files are supported. - for [a workflow method](/use-cases/import-product-feed-to-catalog) - The accepted file format depends on the data source. Refer to the [list of supported sources](/docs/automation/integration) — only Get Data nodes allow sourcing data. - for [API request](https://developers.synerise.com/DataManagement/DataManagement.html#tag/Catalogs) - Data is defined within the request payload. Be sure to follow the request size limits. ### Implementing supplemental catalogs To connect a supplemental catalog to your main item feed, follow these steps: #### Create a catalog to serve as the data source for the supplemental catalog This catalog will hold the data that your supplemental catalog feed will use. 1. Go to

**Data Modeling Hub > Catalogs > New catalog**. 2. In **Catalog name**, provide the name of the catalog. 3. Confirm by clicking **Apply**. **Result**: An empty catalog is added to the catalog list. 4. Upload a file with [the required data](#requirements). - While uploading data to a catalog, you will need to indicate a primary key, for details see [Requirements](#requirements). - You can upload data through the following methods: - through a [simple import](/docs/assets/imports/importing-data-to-catalogs) to a catalog - this lets you conduct a one-off import of data - [through a workflow](/use-cases/import-product-feed-to-catalog) to a catalog - this lets you conduct one-off or cyclical imports to a catalog using the Automation Hub. - [through an API request](https://developers.synerise.com/DataManagement/DataManagement.html#tag/Catalogs/operation/addItemsBatchAsync) to a catalog - this lets you conduct one-off or cyclical imports to a catalog using an API method. #### Create a supplemental catalog feed linked to your catalog This feed lets you use the catalog as a data source for price and availability information for your main item feed and control which item attributes will be available in the **Supplemental attributes** tab in the recommendation filter. 1. Go to **Settings > AI engine configuration > Add feed**. **Result**: A pop-up appears.

A pop-up with selection of the item feed type

2. Select **Catalog**. **Result**:

A pop-up with selection of the item feed type

2. Select **Supplemental catalog**. 3. On the pop-up, from the **Catalog** dropdown list, select the catalog which will [be the source of data](#create-a-catalog-to-serve-as-the-data-source-for-the-supplemental-catalog). **Result**: The supplemental catalog feed is added to the list. 3. Find the created supplemental catalog feed on the list and click it. 3. In the **Product feed connection** section, connect this feed to your main item feed or feeds.

Configuration of the supplemental catalog

4. In the **Filterable attributes** section, you must select the item attributes from the supplemental catalog which will be available in recommendation filters. - The attributes will be available in [recommendation filters](/docs/ai-hub/recommendations-v2/recommendation-filters) in the **Supplemental attributes** tab. - While selecting the attributes to be available in the filters you can define their value types by using: text, range, and datetime options.

Make sure `price.value` is set to **Range** and `channelId` is set to **Text**.

Defining value types for attributes selected in the Filterable attributes section — Defining value types for the attributes selected in the Filterable attributes section

5. In the **Response attributes** section, you must select the item attributes from the supplemental catalog which will be returned in the recommendation. 5. Confirm the settings by clicking **Save**. ## Supplemental attributes A list of item attributes sourced from the supplemental catalog are available in the recommendation filters only when [the item feed is connected with any supplemental catalog](#create-a-supplemental-catalog-feed-linked-to-your-catalog). If several supplemental catalog feeds are connected with the item feed, then this tab gathers all attributes from all supplemental catalogs. - In [the visual builder](/docs/ai-hub/recommendations-v2/recommendation-filters#visual-builder), you can find them in the **Supplemental attributes** tab:

Highlighted tab contains supplemental attributes from the supplemental catalogs connected to the item feed in the filter visual builder

- In the [IQL filter builder](/docs/ai-hub/recommendations-v2/recommendation-filters#iql-query), you can find them in **Supplemental attribute** in the **Attribute** category:

A dropdown for the Attribute category — A dropdown for the Attribute category in IQL filter builder

## Supplemental catalog status You can track item inconsistency for the supplemental catalogs, more information is available in the ["Item consistency" section](/docs/settings/configuration/ai-engine-configuration/feed-status#item-consistency).