JSON / JSONL feed format - items

Sending items (generally products in an e-commerce context) is a key component in defining a customer product catalog.

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 items with item definitions encapsulated in a UTF-8 encoded JSON file named items.json.

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

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 or items.json or items.jsonl) and its variations would be referenced in a variation feed (variations.csv or variations.json or variations.jsonl).

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

Example JSON items file

{
  "items": [
    {
      "id": "cotton-t-shirt",
      "name": "Cotton T-Shirt",
      "url": "https://constructor.com/",
      "image_url": "https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/WOVEN-CASUAL-SHIRT_BUTTON-DOWN-WOVEN-SHIRT_BSH01757SB1918_3_category.jpg",
      "group_ids": [
        "tops-athletic",
        "tops-casual"
      ],
      "data": {
        "product_type": [
          "Shirts",
          "T-Shirts"
        ],
        "material": "Cotton",
        "keywords": [
          "gym",
          "casual",
          "athletic",
          "workout",
          "comfort",
          "simple"
        ],
        "description": "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.",
        "active": true,
        "price": 18
      }
    }
  ]
}

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

Example JSONL items file

{"id": "cotton-t-shirt","name": "Cotton T-Shirt","url": "https://constructor.com/","image_url": "https://constructorio-integrations.s3.amazonaws.com/tikus-threads/2022-06-29/WOVEN-CASUAL-SHIRT_BUTTON-DOWN-WOVEN-SHIRT_BSH01757SB1918_3_category.jpg","group_ids": ["tops-athletic","tops-casual"],"data": {"product_type": ["Shirts","T-Shirts"],"material": "Cotton","keywords": ["gym","casual","athletic","workout","comfort","simple"],"description": "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.","active": true,"price": 18}}

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