JSON / JSONL feed format - item groups (categories)

Item groups (also known as categories, collections, or taxonomy nodes) define the hierarchical structure used to organize your products.
This guide describes how to send item-group data using JSON or JSONL files via HTTP or FTPS uploads.

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, while JSONL file is expected to contain a set of lines where each line is a JSON object string.

File names

• JSON - item_groups.json
• JSONL - item_groups.jsonl

JSON structure

A JSON file wraps an array of item-group objects in a top-level key `item_groups. Each item group in a JSON object containing the following fields:

{
  "item_groups": [
    {
      "id": "tops",
      "name": "Tops",
      "data": {
        "seo_title": "All tops"
      }
    },
    {
      "id": "t-shirts",
      "name": "T-Shirts",
      "parent_id": "tops",
      "data": {
        "seo_title": "T-Shirts for everyone"
      }
    }
  ]
}

JSONL structure

Each line contains a single item-group object identical to an element of the item_groups array above.

{"id": "tops", "name": "Tops", "data": {"seo_title": "All tops"}}
{"id": "t-shirts", "name": "T-Shirts", "parent_id": "tops", "data": {"seo_title": "T-Shirts for everyone"}}

Compression & archives

item_groups.json or .jsonl may be uploaded individually or included in a .tar.gz archive along with items and variations files.

Example files

Example files can be downloaded from GitHub:

• item_groups.json
• item_groups.jsonl

Related guides

• CSV feed format - item groups (categories)
• Full product-catalog overview