> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Category Hierarchy: path Field Now Preferred

> The path field is now the recommended way to define category hierarchies. The parentId field remains fully supported with no plans for removal.

export const ChangelogActions = () => {
  return <>
      <style>{`
        .changelog-actions {
          display: flex;
          justify-content: center;
          gap: 12px;
          margin-top: 2rem;
          padding-top: 1.5rem;
          border-top: 1px solid #e5e7eb;
        }
        
        [data-theme="dark"] .changelog-actions {
          border-top-color: #374151;
        }
        
        .changelog-btn {
          display: inline-flex;
          align-items: center;
          gap: 6px;
          padding: 8px 16px;
          border-radius: 9999px;
          border: 1px solid #d1d5db;
          background: transparent;
          color: #6b7280;
          font-size: 14px;
          cursor: pointer;
          transition: all 0.2s ease;
        }
        
        .changelog-btn:hover {
          border-color: #9ca3af;
          background: #f9fafb;
        }
        
        [data-theme="dark"] .changelog-btn {
          border-color: #4b5563;
          color: #9ca3af;
        }
        
        [data-theme="dark"] .changelog-btn:hover {
          border-color: #6b7280;
          background: #1f2937;
        }
      `}</style>
      <div className="changelog-actions">
        <button className="changelog-btn" onClick={() => {
    const btn = event.target.closest("button");
    btn.innerHTML = "❤️ Like";
    btn.style.borderColor = "#ec4899";
  }}>
          🤍 Like
        </button>
        <button className="changelog-btn" onClick={() => {
    const btn = event.target.closest("button");
    navigator.clipboard.writeText(window.location.href);
    const originalContent = btn.innerHTML;
    btn.innerHTML = "✓ Copied";
    btn.style.borderColor = "#22c55e";
    btn.style.color = "#22c55e";
    setTimeout(() => {
      btn.innerHTML = originalContent;
      btn.style.borderColor = "";
      btn.style.color = "";
    }, 2000);
  }}>
          ↗ Share
        </button>
      </div>
    </>;
};

<div className="cl-badge-group">
  <Badge color="gray" size="sm" icon="calendar">February 26, 2026</Badge>
  <Badge color="blue" size="sm" icon="box">Catalog API</Badge>
  <Badge color="yellow" size="sm" icon="info-circle">Clarification</Badge>
</div>

## What Changed

The [Upsert Categories](/en/api-reference/catalog-api/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.

<Note>
  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.
</Note>

## 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

<Tabs>
  <Tab title="Using path (preferred)">
    ```json theme={null}
    [
      {
        "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"
      }
    ]
    ```
  </Tab>

  <Tab title="Using parentId (still supported)">
    ```json theme={null}
    [
      {
        "id": "apparel-and-accessories",
        "name": "Apparel & Accessories"
      },
      {
        "id": "clothing",
        "name": "Clothing",
        "parentId": "apparel-and-accessories"
      },
      {
        "id": "dresses",
        "name": "Dresses",
        "parentId": "clothing"
      }
    ]
    ```
  </Tab>
</Tabs>

## 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

<ChangelogActions />