Skip to main content
February 26, 2026Catalog APIClarification

​
What Changed

The Upsert Categories endpoint now supports a path field as the preferred way to define category hierarchies. This field uses a dot-separated string to represent a category’s full position in the tree.
The parentId field remains fully supported. There are no plans to remove it. If your integration uses parentId today, it will continue to work as expected.

​
Why We Added path

The path field makes it possible to define a category’s full hierarchy in a single value, without requiring recursive lookups. This is especially useful for features like the Hierarchical Category Tree View, where the full ancestry of a category needs to be known.

​
Comparison

[
  {
    "id": "apparel-and-accessories",
    "name": "Apparel & Accessories",
    "path": "apparel_and_accessories"
  },
  {
    "id": "clothing",
    "name": "Clothing",
    "path": "apparel_and_accessories.clothing"
  },
  {
    "id": "dresses",
    "name": "Dresses",
    "path": "apparel_and_accessories.clothing.dresses"
  }
]

​
What You Should Do

  • New integrations: Use path when setting up category hierarchies
  • Existing integrations using parentId: No action required. parentId continues to work and there are no plans to remove it
  • Both fields provided: If both path and parentId are sent, path takes precedence