Tree Categories

About

The treeCategories query retrieves categories in a hierarchical tree structure, useful for navigation menus and category browsing. This query is essential for:

• Building category navigation menus
• Displaying category hierarchies for storefront
• Managing nested category structures
• Fetching categories with their parent-child relationships
• Building breadcrumb navigation
• Creating category tree widgets

The query returns an array of categories (not a paginated connection) with nested children and translations. Use the parentId argument to filter categories by their parent.

Arguments

Argument	Type	Required	Description
parentId	Int	✅ Yes	The numeric ID of the parent category to filter by. Specifies which level of the tree to retrieve.

Possible Returns

Field	Type	Description
treeCategories	[Category!]!	Array of category objects matching the parent ID filter.

Category Fields

Field	Type	Description
id	String!	Unique identifier in format /api/shop/categories/{id}
_id	Int!	Numeric identifier for the category
position	Int!	Display order position of the category
status	String!	Status of the category ("1" for active, "0" for inactive)
logoPath	String	File path to the category logo
displayMode	String	Display mode (e.g., "products_and_description", "products_only")
_lft	String	Left pointer for nested set tree structure
_rgt	String	Right pointer for nested set tree structure
additional	Mixed	Additional category attributes
bannerPath	String	File path to the category banner
createdAt	String!	Creation timestamp (ISO 8601 format)
updatedAt	String!	Last update timestamp (ISO 8601 format)
url	String	Full URL to the category page
logoUrl	String	Full URL to the category logo image
bannerUrl	String	Full URL to the category banner image
translation	CategoryTranslation	Default translation object with name, slug, and urlPath
translations	Connection	Paginated translations for all locales
children	Connection	Paginated child categories with their details

Common Use Cases

Get Root Categories for Main Menu

query GetRootCategories {
  treeCategories(parentId: 1) {
    id
    _id
    position
    status
    translation {
      name
      slug
      urlPath
    }
    logoUrl
    children(first: 50) {
      edges {
        node {
          id
          position
          translation {
            name
            slug
          }
        }
      }
    }
  }
}

Get Category Tree with Full Details

query GetCategoryTree {
  treeCategories(parentId: 1) {
    id
    _id
    position
    status
    logoPath
    logoUrl
    bannerUrl
    displayMode
    url
    translation {
      name
      slug
      description
    }
    children(first: 100) {
      edges {
        node {
          id
          position
          translation {
            name
            slug
            urlPath
          }
        }
      }
    }
  }
}

Get Specific Subtree by Parent

query GetCategorySubtree {
  treeCategories(parentId: 2) {
    id
    position
    translation {
      name
      slug
    }
    children(first: 50) {
      edges {
        node {
          id
          position
          translation {
            name
            slug
            urlPath
          }
        }
      }
    }
  }
}

Get Categories with Translations

query GetCategoriesWithTranslations {
  treeCategories(parentId: 1) {
    id
    position
    translation {
      name
      slug
      description
    }
    translations(first: 10) {
      edges {
        node {
          locale
          name
          slug
          description
        }
      }
      totalCount
    }
    children(first: 100) {
      edges {
        node {
          id
          position
          translation {
            name
          }
        }
      }
    }
  }
}

Error Handling

Invalid Parent ID - Non-integer Value

{
  "errors": [
    {
      "message": "Int cannot represent non-integer value: dffddf"
    }
  ]
}

Invalid Parent ID - String Instead of Integer

{
  "errors": [
    {
      "message": "Int cannot represent non-integer value: \"1111\""
    }
  ]
}

Parent ID Not Found

{
  "data": {
    "treeCategories": []
  }
}

Best Practices

1. Always Provide parentId - The parentId parameter is required
2. Use First for Children Pagination - Limit child categories with the first argument (e.g., first: 100)
3. Request Only Needed Fields - Reduce payload by selecting specific fields
4. Cache Navigation Data - Categories change infrequently; implement caching
5. Handle Status Filtering - Filter by status="1" on client side if needed
6. Use Translation Fields - Include translation data for multi-language support
7. Paginate Nested Collections - Use first argument for children and translations
8. Use Position Field - Order results by position field for proper display

Related Resources

• Get Single Category - Retrieve a single category by ID
• Get Categories - List all categories with pagination
• Pagination Guide - Cursor pagination documentation
• Shop API Overview - Overview of Shop API resources