JSON / JSONL 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 JSON or JSONL files, please use a standard JSON library in the programming language of your choice. Some standard libraries we recommend for different languages are:

• Java: jackson
• JavaScript: native support
• Ruby: yajl-ruby
• Python: JSON

The difference between JSON and JSONL is that JSON file is expected to contain only a JSON object string, while JSONL file is expected to contain a set of lines where each line is a JSON object string.

In case of JSON a file has the same format as the request body in Create or replace variations with item definitions encapsulated in a UTF-8 encoded JSON file named variations.json.

In case of JSONL an each line has the same format as an element of variations array in Create or replace variations with item definitions encapsulated in a UTF-8 encoded JSONL file named variations.jsonl.

Some items may have variations, while others may not. Sending a variations file is optional.

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.json/jsonl file may be included as part of a compressed archive file.

Example JSON variations file

{
  "variations": [
    {
      "id": "cotton-t-shirt-red",
      "item_id": "cotton-t-shirt",
      "name": "Cotton T-Shirt - Red",
      "data": {
        "image_url": "https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/KNIT-CASUAL-SHIRT_BUTTON-DOWN-KNIT-SHIRT_BKT00110SR1734_3_category.jpg",
        "url": "https://constructor.com/",
        "color": "Red",
        "active": true
      }
    },
    {
      "id": "cotton-t-shirt-blue",
      "item_id": "cotton-t-shirt",
      "name": "Cotton T-Shirt - Blue",
      "data": {
        "image_url": "https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/WOVEN-CASUAL-SHIRT_BUTTON-DOWN-WOVEN-SHIRT_BSH01757SN1770_3_category.jpg",
        "url": "https://constructor.com/",
        "color": "Blue",
        "active": false
      }
    }
  ]
}

An example variations.json file can be viewed and downloaded from GitHub.

Example JSONL variations file

{"id": "cotton-t-shirt-red","item_id": "cotton-t-shirt","name": "Cotton T-Shirt - Red","data": {"image_url": "https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/KNIT-CASUAL-SHIRT_BUTTON-DOWN-KNIT-SHIRT_BKT00110SR1734_3_category.jpg","url": "https://constructor.com/","color": "Red","active": true}}
{"id": "cotton-t-shirt-blue","item_id": "cotton-t-shirt","name": "Cotton T-Shirt - Blue","data": {"image_url": "https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/WOVEN-CASUAL-SHIRT_BUTTON-DOWN-WOVEN-SHIRT_BSH01757SN1770_3_category.jpg","url": "https://constructor.com/","color": "Blue","active": false}}

An example variations.jsonl file can be viewed and downloaded from GitHub.