CSV feed format - items (products)
Sending items (generally products in an e-commerce context) is a key component in defining a customer product catalog.
When creating CSV files, please use a standard CSV library in the programming language of your choice. The CSV specification is quite detailed, and is more complex than simply separating fields with commas. Some standard libraries we recommend for different languages are:
- Java: Apache Commons CSV
- JavaScript: Papa Parse
- Ruby: CSV
- Python: CSV
Item definitions are encapsulated in a UTF-8 encoded CSV file named items.csv with the data defined below:
| Field Name | Required | Description |
|---|---|---|
id | ✔ | A unique item ID that is available for the beacon to track (in the DOM or on the window object ) across your search results, browse results, and product detail pages. Limited to 250 characters. |
item_name | ✔ | The name to display in results. Limited to 250 characters. |
url | ✔ | The page URL a user is taken to after selecting an item in autocomplete, search, browse, or recommendation results. |
image_url | ✔ | An image URL for the item. We recommend image dimensions of at least 400 pixels per side. |
facet:[name] | ⚠️ Warning: ingesting data directly as facets has been deprecated. Please ingest the data as metadata instead, and create a facet configuration as shown in our guide on global facet configuration. | |
group_ids | A pipe-separated list of group IDs (categories) this item is associated with. Each item may belong to one group, multiple groups, or no groups at all. These must correspond to the IDs uploaded in the item groups (category) file. | |
keywords | Key terms or phrases that help users find the item, separated by pipe characters (|). The maximum length of this field is 1,000 characters. | |
description | The item description. Limited to 1,000 characters. | |
metadata:[name] | Custom metadata indicating data points like inventory levels, promotional details, and other product-specific information. Each field can be individually configured to be searchable, displayable (that is, returned with the search results), or both. The fields should be prefixed with the string metadata:[name], for example: metadata:price. 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:notes.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. Please refer to the Facets & metadata guide for more information on facets and metadata. | |
active | TRUE or FALSE. To remove items from results but maintain them in Constructor's catalog, set this to FALSE. It is highly recommended to use this flag when products temporarily go out of stock in order to maintain their behavioral learnings, rather than removing products entirely. Defaults to TRUE. |
Unrecognized columns in the feed will be ignored by our ingestion process.
For a description of what defines a facet and what defines metadata, please refer to the Facets & metadata guide.
Product data can also include variations or variants, such as when a shirt has multiple colors or sizes. In this case, the general shirt product would appear in the product feed (items.csv) and its variations would be referenced in a variation feed (variations.csv).
All other fields that can be included in the product feed can also be included in the variation feed. When displaying results, Constructor's machine learning algorithm choose the best variation to display. If you'd like to define your own default variation, you can pass the field metadata:is_default with the value "true" in the variation data.
There is no hard limit on the number of variations allowed per item as we have customers with thousands of variations on items. An item may belong to one or many item groups.
The items.csv file must be included as part of a compressed archive file. The maximum size per row within the items.csv and variations.csv files is 150kb.
Example items file
id,item_name,url,image_url,group_ids,metadata:product_type,metadata:json:material,keywords,description,metadata:price,active
cotton-t-shirt,Cotton T-Shirt,https://constructor.com/,https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/WOVEN-CASUAL-SHIRT_BUTTON-DOWN-WOVEN-SHIRT_BSH01757SB1918_3_category.jpg,tops-athletic|tops-casual,Shirts|T-Shirts,"Cotton","[""gym"",""casual"",""athletic"",""workout"",""comfort"",""simple""]","Treat yourself to a comfy upgrade with this Short Sleeve Shirt from Etchell's Emporium. This short-sleeve T-shirt comes with a classic crew-neck, giving you style and comfort that can easily be paired with a variety of bottoms.",18.00,TRUE
An example items.csv file can be viewed and downloaded from GitHub.
Updated 3 days ago