JSON / JSONL feed format - item groups (categories)

Suggest Edits

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:

Field Name	Required	Description
`id`	✔	A unique group ID that is available for the beacon to track (in the DOM or on the window object) for each browse result page. Limited to 250 characters.
`name`	✔	The name of the item group. Limited to 250 characters.
`parent_id`		DEPRECATED. Consider using `parent_ids` instead
`parent_ids`	✔	The IDs for the item groups this group belongs to. Should be formatted as JSON array of strings. Each id is limited to 250 characters.
`data`		JSON metadata associated with the item group. Limited to 5kb.

{
  "item_groups": [
		{
      "id": "all",
      "name": "All",
      "data": {},
      "parent_ids": []
    },
    {
      "id": "tops",
      "name": "Tops",
      "parent_ids": ["all"],
      "data": {
        "seo_title": "All tops"
      }
    },
    {
      "id": "summer-tops",
      "name": "Summer Tops",
      "parent_ids": ["tops", "all"],
      "data": {
        "seo_title": "Summer Tops for all"
      }
    }
  ]
}

JSONL structure

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

{"id": "all", "name": "All", "data": {}, "parent_ids": []}
{"id": "tops", "name": "Tops", "parent_ids": ["all"], "data": {"seo_title": "All tops"}}
{"id": "summer-tops", "name": "Summer Tops", "parent_ids": ["tops", "all"], "data": {"seo_title": "Summer Tops for all"}}

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:

Related guides

Updated 15 days ago