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
- 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 |
|---|---|---|
| ✔ | A unique and canonical ID for the item variation. Limited to 250 characters, case sensitive. |
| ✔ | The canonical ID for the item this variation belongs to (must be defined in |
| The name to display in results. When provided, it will be used in favor of the | |
| The page URL a user is taken to after selecting an item in autocomplete, search, browse, or recommendation results. | |
| The image URL for the item variation. We recommend image dimensions of at least 400 pixels per side. | |
| The item variation description. Limited to 1,000 characters. | |
| Key terms or phrases that help users find the item variation, separated by pipe characters ( | |
| 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 If the values contain JSON data, use the prefix 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. | |
| ⚠️ Warning: ingesting data directly as facets has been deprecated. | |
|
|
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,FALSEAn example variations.csv file can be viewed and downloaded from GitHub.
Updated 28 days ago