Product Insights Agent requires item data and content to determine and deliver accurate responses to shoppers’ product-related questions.

Below, we walk through the necessary steps to upload item data and content to power the Product Insights Agent.

Step 1: Review catalog data

The first step is to ensure your catalog data contains the necessary item data. This should, at minimum, include:

Item name
Item id
Item description

The file can also include additional fields, such as product URL, group id, and item metadata. You’ll want to ensure that these fields reflect the level of item detail you wish to have available to the agent.

While you only need the above data points to get started, we recommend sending all available catalog product data displayed on a product detail page (PDP). The more data the agent has to work with, the richer, and more accurate the agent’s answers will be. For example, if a PDP is for a couch, then sending all the facet and metadata on the PDP, such as seating material, capacity, recliner status, brand, designer, materials, etc., would allow the agent to inform a shopper whether the product is right for them.

Metadata and facets you wish to be available to the Product Insights Agent should be marked as visible.

Step 2: Upload item reviews (optional)

Item reviews help train your agent to understand what real shoppers say about items in your catalog.

⚠️ Please note: Before uploading reviews, please contact your CSM so they can create a new section in the correct index.

There are two methods of upload:

FTPS: You will need to include the section name in the filename.
HTTP: You will need to ensure you define the section parameter to include the section name.

Please only upload reviews for items in your current catalog.

Reviews data format

Field name	Type	Required	Description
`id`	string	✓	A unique identifier for the review. Limited to 250 characters.
`metadata:item_id`	string	✓	A unique identifier for the product being reviewed (`item id` from the Products catalog).
`metadata:review`	string	✓	The text content of the review.
`metadata:rating`	integer	Strongly encouraged	The rating given in the review (typically from 1 to 5).
`metadata:variation_id`	string		A unique identifier for the product variation being reviewed (variation_id from the Variations catalog).
`metadata:name`	string		The title of the review. Example: "Perfect! Just what we were looking for!"
`metadata:tm`	string (ISO 8601 timestamp)		The timestamp when the review was created. It uses a precise timestamp format for accuracy, but such accuracy is not required. Example: 2022-09-01 03:00:26.369
`metadata:[name]`			Custom metadata indicating data points like review moderation status, user purchase credentials, urls of attached images, and other review-specific information. The fields should be prefixed with the string `metadata:[name]`. For example: `metadata:moderation_status`. There is not a pre-defined list of metadata names; rather, they can be arbitrary according to what is most useful. If the values contain JSON data, use the prefix `metadata:json:[name]`. For example: `metadata:json:images_urls`. The maximum length of the names of metadata fields is 1,000 characters. There is no limit on the size of the values, but please work with your integration contact if you plan to upload large values.

CSV upload format for reviews

If you are using CSV upload format, metadata:<...> fields should be uploaded in a single JSON column named metadata with corresponding field names.

Example CSV

id,metadata
abc,"{""item_id"":""def"", ""review"": ""Great product!""}"

Example item review upload

Here is an example of how the data would be uploaded. Please note that not all information from the above table is included in this example.

{
  "id": "NCjyD6Sveet1B4TgbQII",
  "tm": "2022-09-01 03:00:26.369",
  "name": "A Very Healthy Probiotic",
  "facets": {
  },
  "rating": 5,
  "review": "No refrigeration needed! Keeps my system happy and working efficiently.",
  "variation_id": 5555,
  "deactivated": false
}

Step 3: Upload blog, knowledge base articles, and guide content (optional)

Long-form content, such as blog articles, how-to help articles, and guides can train your agent to understand broader concepts and information related to items in your catalog.

⚠️ Please note: Before uploading reviews, please contact your CSM so they can create a new section in the correct index.

There are two methods of upload:

FTPS: You will need to include the section name in the filename.
HTTP: You will need to ensure you define the section parameter to include the section name.

Please note that, for content files, there is a 20KB size limit per article and 50,000 limit on the number of articles.

Blog, knowledge base articles, and guides data format

Field name	Type	Required	Description
`id`	string	✓	A unique identifier for the article or guide. Limited to 250 characters.
`item_name`	string	✓	Article title describing article topic or purpose
`url`	string	Strongly encouraged	URL where the article lives on your site.
`description`	string	Strongly encouraged	Short summary of article contents
`keywords`	string	Strongly encouraged	Keywords/tags related to article topic, purpose, type, or usage, separated by pipe characters (\|) Example: gym\|casual\|athletic\|workout\|comfort
`image_url`	string		Image URL for article cover
`metadata:content_text`	string	✓	Text of the article
`metadata:created_at`	string (ISO 8601 timestamp)	Strongly encouraged	The timestamp when the article was created/published. It uses a precise timestamp format for accuracy, but such accuracy is not required. example: 2022-09-01 03:00:26.369
`metadata:moderation_status`	string		Status of the article (published/draft/archived) Example: Published
`metadata:related_groups`	json		List of group ids of related product categories (i.e.,`id` from item groups (categories)) Example: `"[‘tops-athletic’, ‘tops-casual’]”`
`metadata:related_products`	json		List of related product ids referenced in the article (i.e., `id` from items (products))
`metadata:related_articles`	json		List of IDs of any related articles within your knowledge base
`metadata:related_searches`	json		List of related searches Example: `"[‘athletic tops’,’casual tops’]”`
`metadata:[name]`			Custom metadata indicating data points like user interaction data, urls of attached images, and other article-specific information. There is not a pre-defined list of metadata names; rather, they can be arbitrary according to what is most useful. The maximum length of the names of metadata fields is 1,000 characters.

CSV upload format for articles and knowledge base data