Skip to main content

Item Groups

Item groups allow customers to communicate information about the hierarchy of categories associated with their items (typically, their products). This information powers hierarchical category faceting and search-in-category autosuggest suggestions.

Hierarchy

The data about the hierarchy of item groups is edited independently of the item records themselves to allow flexibility to define or redefine group hierarchies.

Scope

Item groups are set at the level of each search key, so separate keys in one account can contain different group hierarchies.

Add item group​

An item group can be added by passing its id, name, parent_id (the id of the parent item group if any) and data.

Add item group
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "<item_group_name>", "parent_id": "<item_group_parent_id>", "data": {"foo": "bar"}}' \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/<item_group_id>?key=[your API key]"
response
{
  "id": "<item_group_id>",
  "name": "<item_group_name>",
  "parent_id": "<item_group_parent_id>",
  "data": { "foo": "bar" }
}

HTTP request​

PUT https://ac.cnstrc.com/v1/item_groups/[item_group_id]?key=[your API key]

JSON parameters​

ParameterRequired?Description
nameNoItem group display name.
parent_idNoParent item group customer ID or null for root item groups.
dataNoJSON object with custom metadata attached with the item group. Defaults to null if not provided.

Update item group​

An item group can be updated by passing its id, name, parent_id (the id of the parent item group if any) and data. When only one of name, parent_id or data needs to be updated, the other one doesn't need to be passed in the request body.

Update item group
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"name": "<new_item_group_name>", "parent_id": "<new_parent_item_group_id>", "data": {"foo": "bar"}}' \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/<item_group_id>?key=[your API key]"
Response
{
  "id": "<item_group_id>",
  "name": "<new_item_group_name>",
  "parent_id": "<new_item_group_parent_id>",
  "data": { "foo": "bar" }
}

HTTP request​

PUT https://ac.cnstrc.com/v1/item_groups/[item_group_id]?key=[your API key]

JSON parameters​

ParameterRequired?Description
nameNoItem group display name.
parent_idNoParent item group customer ID or null for root item groups.
dataNoJSON object with custom metadata attached with the item group.

Add multiple item groups​

Item groups can be added to a key using a json payload that describes the item groups hierarchy using the following schema for each item group element:

AttributesTypeDescription
idstringItem group customer ID.
namestringItem group display name.
dataobjectJSON object with custom metadata attached with the item group.
childrenList[item_group]List of item groups categorized under the current item group.

Note: Up to 1,000 item groups can be submitted in a single request. However, there is no limit to the depth of nested groups within an item group.

There are two different HTTP methods depending on the desired update semantics:

  • POST: item groups that already exist will be skipped (see examples #1 and #2).
  • PATCH: item groups that already exist will be updated (see examples #3 and #4).

Insert new item groups and skip existing ones​

Request example #1: json payload with new item groups
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_1>",
            "name": "<group_name_1>",
            "data": {"foo": "bar"}
          },
          {
            "id": "<group_id_2>",
            "name": "<group_name_2>"
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"
Response example #1: all new item groups were inserted
{
  "item_groups": {
    "processed": 2,
    "inserted": 2,
    "updated": 0
  }
}
Request example #2: json payload with updated item group
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_1>",
            "name": "<group_name_1>",
            "children": [
              {
                "id": "<group_id_2>",
                "name": "<new_group_name_2>",
                "data": {"foo": "bar"}
              }
            ]
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"
Response example #2: existing item group was skipped (not updated)
{
  "item_groups": {
    "processed": 2,
    "inserted": 0,
    "updated": 0
  }
}

HTTP request​

POST https://ac.cnstrc.com/v1/item_groups?key=[your API key]

JSON parameters​

ParameterRequired?Description
item_groupsYesA list of item groups

Insert new item groups and update existing ones​

Request example #3: add new item groups
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_3>",
            "name": "<group_name_3>",
          },
          {
            "id": "<group_id_4>",
            "name": "<group_name_4>"
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"
Response example #3: all new item groups were inserted
{
  "item_groups": {
    "processed": 2,
    "inserted": 2,
    "updated": 0
  }
}
Request example #4: json payload with updated item group
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{
        "item_groups": [
          {
            "id": "<group_id_3>",
            "name": "<group_name_3>",
            "children": [
              {
                "id": "<group_id_4>",
                "name": "<new_group_name_4>"
              }
            ]
          }
        ]
      }' \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"
Response example #4: existing item group was updated
{
  "item_groups": {
    "processed": 2,
    "inserted": 0,
    "updated": 1
  }
}

HTTP request​

PATCH https://ac.cnstrc.com/v1/item_groups?key=[your API key]

JSON parameters​

ParameterRequired?Description
item_groupsYesA list of item groups

Get item groups​

Retrieves item groups for a given key in a tree structure. If no group_id is specified, returns a list consisting of all top-level groups (groups without any parents), and their descendants. If a group_id is specified, returns a list consisting of the group with that group_id, and its descendants. All groups are linked to their children through the children field.

curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"
curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/123?key=[your API key]"

HTTP Requests​

GET https://ac.cnstrc.com/v1/item_groups?key=[your API key]

GET https://ac.cnstrc.com/v1/item_groups/[group id]?key=[your API key]

Response format​

Request example #1: get all item groups
curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"
Response example #1
{
  "item_groups": [
    {
      "id": "1",
      "name": "group 1",
      "data": { "foo": "bar" },
      "children": [
        {
          "id": "3",
          "name": "group 3",
          "data": null,
          "children": []
        }
      ]
    },
    {
      "id": "2",
      "name": "group 2",
      "data": null,
      "children": []
    }
  ],
  "total_count": 3
}
Request example #2: get specific item group with id
curl -X GET -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups/2?key=[your API key]"
Response example #2
{
  "item_groups": [
    {
      "id": "2",
      "name": "group 2",
      "data": null,
      "children": []
    }
  ],
  "total_count": 1
}

URL Parameters​

ParameterDescription
group idThe group id you'd like to retrieve results for.

Query Parameters​

ParameterRequired?Description
keyYesThe index you'd like to to retrieve results from.

Delete item groups​

Request example
# Delete item groups
curl -X DELETE \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/item_groups?key=[your API key]"

Delete all item groups for a given key.

HTTP request​

DELETE https://ac.cnstrc.com/v1/item_groups?key=[your API key]