CSV feed format - variations
Item data (products) 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 items feed and its variations would be referenced in a variation feed.
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
Some items may have variations, while others may not. Sending a variations file is optional.
Variation definitions are encapsulated in a UTF-8 encoded CSV file named variations.csv with the data defined below:
| Field Name | Required | Description |
|---|---|---|
variation_id | ✔ | A unique and canonical ID for the item variation. Limited to 250 characters. |
item_id | ✔ | The canonical ID for the item this variation belongs to (must be defined in items.csv). |
item_name | The name to display in results. When provided, it will be used in favor of the item_name defined within the items.csv file. 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 | The image URL for the item variation. We recommend image dimensions of at least 400 pixels per side. | |
description | The item variation description. Limited to 1,000 characters. | |
keywords | Key terms or phrases that help users find the item variation, separated by pipe 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.Note that the maximum length of the names of the 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. | |
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 . | |
active | TRUE or FALSE. To remove item variations 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 |
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.
The variations.csv file must be included as part of a compressed archive file.
Example variations file
variation_id,item_id,item_name,image_url,metadata:color,url,active
cotton-t-shirt-red,cotton-t-shirt,Cotton T-Shirt - Red,https://constructor.com/media/cotton-t-shirt.jpg,Red,https://constructor.com/products/cotton-t-shirt-red,TRUE
cotton-t-shirt-blue,cotton-t-shirt,Cotton T-Shirt - Blue,https://constructor.com/media/cotton-t-shirt-blue.jpg,Blue,https://constructor.com/products/cotton-t-shirt-blue,FALSE
An example variations.csv file can be viewed and downloaded from GitHub.
Updated 3 days ago