You can import your product catalog using a CSV file, by reusing an existing file, whether it is a Google Shopping format or another format you already use.

If you need to create a new CSV file specifically for the catalog, the data feed description below specifies the essential information to include.

The product catalog provides your Assistant with the data needed to help customers in their search and answer questions about product characteristics. An optimal structure for this CSV file is therefore crucial to ensure efficient operation.

1. Data feed description

1.1. File format

The CSV file must include a header row indicating the content of each column, followed by one row per product. The columns must list the product characteristics such as Title, Description, Price, etc.

A sample CSV file is available from this link. Make sure to use the CSV format with UTF-8 encoding to avoid any errors during import.

1.2. Expected data

Required fields:

id : Unique product identifier
title : Title
description : Description
link : URL of the product page on your website

Other fields that are not required but strongly recommended:

item_group_id : Group ID (to group variants of the same product: sizes, colors, materials, conditions)
availability : Availability
Standard values: in_stock, out_of_stock, preorder, backorder

The system also accepts:
- Writing variations: uppercase/lowercase, with or without hyphens/spaces (e.g.: in stock, IN-STOCK)
- Numeric values: 0 or negative = out of stock | positive number = in stock
- Multilingual synonyms: yes, true, disponible = in stock | no, false, non = out of stock
The system automatically normalizes these values to one of the 4 standard statuses.
availability_date : Availability date
price : Price
sale_price : Sale price
image_link : URL of the product's main image

Required for the product discovery feature of your AI Shopping Assistant
additional_image_link : URL(s) of additional product images

Required for the product discovery feature of your AI Shopping Assistant
product_types : Product category

Example value: Home > Men > Clothing > Shirts
gender : Gender

Supported values: male, female, unisex
brand : Brand
color : Color

Main color listed first
size : Size
material : Material

Can consist of a primary material and secondary materials separated by a comma, slash…
condition : Condition

Supported values: new, refurbished, used
crosssellproducts : Additional sales (cross selling)
compatiblewith : Compatibility (learn more)

This information is essential to provide an optimal experience for your visitors. If it is not correctly filled in for the majority of products, the catalog cannot be activated or used by your Assistant.

The CSV file can contain additional columns to enrich your Assistant. You have two options:

Use the mapping feature to define the content of the additional columns, such as color or size.
Let our system record this information as supplementary data. In this case, make sure that the column names are explicit, for example: "Manufacturing lead time" or "Power supply wattage".

Once your product catalog is created, use the knowledge explorer to verify that all the information provided is correctly integrated into the knowledge base.

1.3. Data updates

Three import methods are available for your CSV file: Local file, URL and SFTP. The chosen import method determines how your data can be updated.

Local file

When you import a file from your computer, updating your data is manual. To refresh the catalog, you must import a new file directly from your knowledge source.

URL

When you import your CSV file via a URL, iAdvize automatically re-downloads the file hosted at that address according to the frequency you configure.

By default, the update is daily at 03:00 (GMT+02:00, Europe/Paris).

For the URL method, you can customize the update frequency from your knowledge settings:

Select the desired frequency: Daily or Weekly.
Set the update time and the time zone.
Click Save in the top right corner of the screen.

SFTP

The SFTP (Secure File Transfer Protocol) method allows iAdvize to connect directly to your SFTP server each day to automatically retrieve your catalog file. This method is suitable when your files are hosted on an internal SFTP server.

To configure the SFTP import, fill in the following fields:

Host: address of your SFTP server (e.g.: sftp.mycompany.com)
Port: connection port (e.g.: 22)
Username: server login credentials
Password: password associated with this username
Directory: path to the folder containing your catalog file (e.g.: / for the root)
File name pattern (optional): allows you to target a specific file via a regular expression (e.g.: catalog_.*\.csv). If multiple files match the pattern, the most recently modified file is imported.
CSV column separator: select the separator used in your file.

By default, the update is daily at 03:00 (GMT+02:00, Europe/Paris).

For the SFTP method, you can customize the update frequency from your knowledge settings:

Select the desired frequency: Daily or Weekly.
Set the update time and the time zone.
Click Save in the top right corner of the screen.

1.4. Managing product variants

When a product exists in multiple variations (size, color, material, etc.), each variant must be represented by a separate row in the CSV file. All variants of the same product are linked together through the item_group_id field, which must carry the same value for the entire group.

Structuring rules to follow:

Each variant has a unique id that identifies it individually.
All variants of the same product share the same item_group_id.
The item_group_id field must be filled in on each variant row.

Example:

A pair of jeans available in three colors is structured as follows in the catalog:

id	title	color	item_group_id
79052-BRU	Straight cut jeans – Raw	Raw	79052
79052-NOI	Straight cut jeans – Black	Black	79052
79052-DEL	Straight cut jeans – Washed	Washed	79052

Each variant has its own id and all share the same item_group_id: 79052.

⚠ Do not include a "parent" or "group" row in the catalog.

Some catalog formats include an additional row whose id matches the item_group_id value of the variants, without that row itself being a real purchasable variant (no color, size, or stock of its own).

This type of row does not comply with the expected structure for the Assistant and can cause undesired behavior:

The Assistant may identify this row during product search, but the add to cart (Add-To-Cart) feature will not work correctly, as this row does not correspond to any real variant.
The variant selection presented to the visitor will be incorrect or absent.

If your catalog contains this type of row, delete it. Only rows corresponding to real purchasable variants should be present.

NB The Add-To-Cart feature identifies products via the id field (unique variant identifier) and not via the item_group_id field. It is therefore essential that each row in the catalog represents a real variant, with its own id and a filled-in item_group_id.

2. Creating the product catalog with the CSV file

If authentication is required to access your file via URL, add the necessary information in the headers.

If your file does not use the standard CSV format (comma, semicolon, tab, etc.), adjust the field separator to ensure correct parsing.

When the columns in your file use standard labels, they are automatically recognized and mapped to the corresponding fields. Additional columns not configured in the mapping will be added as supplementary information, provided their name is explicit enough to be interpreted correctly.

Your information must be regularly updated to ensure that your Assistant always has the most up-to-date information about your products.

NB When importing your CSV file (via URL, local file, or SFTP), a preliminary check is performed on the first 10,000 rows of the file. This allows potential errors to be detected immediately before launching the full ingestion, making the process smoother, especially for large files.

3. Error management

In case of an error, an explanatory message specifies the reasons for the problem.

CSV file errors

The most common errors include:

Incorrect separator: The specified separator does not match the file format.
Non-compliant CSV format: Some rows do not contain the same number of columns. Each row must have a fixed number of columns, even if some are empty.
Non-compliant encoding: The file is not encoded in UTF-8.
Invalid field format: The content of one or more fields does not follow the expected specifications (see the product catalog field requirements).

SFTP connection errors

The table below lists the error messages that may occur.

Error message	Probable cause	Corrective action
`Error while retrieving file from SFTP host=… : Exhausted available authentication methods`	The username or password is incorrect.	Check and correct the login credentials entered in the configuration.
`Error while retrieving file from SFTP host=…`	The host name is incorrect or the server is unreachable.	Check the host address and make sure the SFTP server is accessible from the Internet.
`Error while retrieving file from SFTP host=… : No eligible files with extension csv or xml has been found on the ftp server`	The directory entered is incorrect or no file matches the file name pattern defined.	Check the directory path and the file name pattern. Make sure a `.csv` or `.xml` file is present in the target folder.

Tips If an error persists on the SFTP connection, check that your server allows incoming connections from iAdvize IP addresses. Contact your technical team if necessary.

You can import your product catalog using a CSV file, reusing an existing file, whether it's in Google Shopping format or another format you are already using.

If you need to create a new CSV file specifically for the catalog, the data feed description below outlines the essential information to include.

The product catalog provides the Assistant with the necessary data to assist customers in their search and answer questions regarding product characteristics. Therefore, an optimal structure of this CSV file is crucial to ensure effective functionality.