Implement Categories on the Storefront

Managing categories with Commerce projects that use Merchandising Services for Adobe Commerce Optimizer requires managing two types of operations:

Create category data using the categories operations available in the Data Ingestion API, and using the products operations to manage product category assignments.
Retrieve category data for storefront display and navigation using the navigation and categoryTree queries available in the Merchandising Services GraphQL API.

For Commerce sites with an Adobe Commerce as a Cloud Service or Adobe Commerce on Cloud infrastructure backend, use the Commerce REST API and the Catalog Service GraphQL API to manage categories.

CategoryView2 interface

The CategoryView2 interface provides a minimal, streamlined set of category fields—slug and name—optimized for typical storefront display and navigation scenarios.

Interface definition

interface CategoryViewV2 {
    slug: String!
    name: String!
}
Copied to your clipboard
interface CategoryViewV2 {
    slug: String!
    name: String!
}

Fields

Field	Data type	Description
`slug`	String!	The unique URL-friendly identifier for the category, used in routing and navigation
`name`	String!	The display name of the category as shown to customers

Key benefits

Lightweight Design: Contains essential fields (slug and name) for optimal performance
Extensible: Serves as a base interface for specialized category types

Category types

The CategoryViewV2 interface is implemented by two specialized types:

CategoryNavigationView - For menu rendering and navigation
CategoryTreeView - For hierarchical category management (primarily RetailCMS)

CategoryNavigationView

The CategoryNavigationView type implements CategoryViewV2 and is specifically designed for building storefront navigation menus with built-in performance optimizations.

Type definition

type CategoryNavigationView implements CategoryViewV2 {
    slug: String!
    name: String!
    children: [CategoryNavigationView]
}
Copied to your clipboard
type CategoryNavigationView implements CategoryViewV2 {
    slug: String!
    name: String!
    children: [CategoryNavigationView]
}

Performance safeguards

Depth Limitation: Menu depth is limited to 4 levels maximum
Lightweight Attributes: Excludes heavyweight category attributes redundant for menu rendering
Single Query: Retrieves entire family in one database query
Heavy Caching: Query responses are heavily cached for optimal performance

CategoryTreeView type

The CategoryTreeView type implements CategoryViewV2 and provides comprehensive hierarchical category data, primarily designed for RetailCMS applications.

Type definition

type CategoryTreeView implements CategoryViewV2 {
    slug: String!
    name: String!
    level: Int
    parentSlug: String
    childrenSlugs: [String]
}
Copied to your clipboard
type CategoryTreeView implements CategoryViewV2 {
    slug: String!
    name: String!
    level: Int
    parentSlug: String
    childrenSlugs: [String]
}

Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards.

type Query {
    navigation(family: String!): [CategoryNavigationView]
}
Copied to your clipboard
type Query {
    navigation(family: String!): [CategoryNavigationView]
}

Query:

query GetTopMenuNavigation {
    navigation(family: "Top-menu") {
        slug
        name
        children {
            slug
            name
            children {
                slug
                name
            }
        }
    }
}
Copied to your clipboard
query GetTopMenuNavigation {
    navigation(family: "Top-menu") {
        slug
        name
        children {
            slug
            name
            children {
                slug
                name
            }
        }
    }
}

Response:

{
    "data": {
        "navigation": [
            {
                "slug": "men",
                "name": "Men clothing",
                "children": []
            }
        ]
    }
}
Copied to your clipboard
{
    "data": {
        "navigation": [
            {
                "slug": "men",
                "name": "Men clothing",
                "children": []
            }
        ]
    }
}

Query:

query GetFullMenuNavigation {
    navigation(family: "menu") {
        slug
        name
        children {
            slug
            name
            children {
                slug
                name
                children {
                    slug
                    name
                }
            }
        }
    }
}
Copied to your clipboard
query GetFullMenuNavigation {
    navigation(family: "menu") {
        slug
        name
        children {
            slug
            name
            children {
                slug
                name
                children {
                    slug
                    name
                }
            }
        }
    }
}

Response:

{
    "data": {
        "navigation": [
            {
                "slug": "men",
                "name": "Men clothing",
                "children": [
                    {
                        "slug": "men/tops",
                        "name": "Men tops",
                        "children": [
                            {
                                "slug": "men/tops/jackets",
                                "name": "Jackets",
                                "children": []
                            }
                        ]
                    }
                ]
            }
        ]
    }
}
Copied to your clipboard
{
    "data": {
        "navigation": [
            {
                "slug": "men",
                "name": "Men clothing",
                "children": [
                    {
                        "slug": "men/tops",
                        "name": "Men tops",
                        "children": [
                            {
                                "slug": "men/tops/jackets",
                                "name": "Jackets",
                                "children": []
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

CategoryTree query

Retrieve hierarchical category data in a tree structure with parent-child relationships and level information.

type Query {
    categoryTree(family: String, slugs: [String], depth: Int): [CategoryTreeView]
}
Copied to your clipboard
type Query {
    categoryTree(family: String, slugs: [String], depth: Int): [CategoryTreeView]
}

Example: Retrieve full category tree

Query:

query GetFullCategoryTree {
    categoryTree(family: "main-catalog") {
        slug
        name
        level
        parentSlug
        childrenSlugs
    }
}
Copied to your clipboard
query GetFullCategoryTree {
    categoryTree(family: "main-catalog") {
        slug
        name
        level
        parentSlug
        childrenSlugs
    }
}

Response:

{
    "data": {
        "categoryTree": [
            {
                "slug": "men",
                "name": "Men's Clothing",
                "level": 0,
                "parentSlug": null,
                "childrenSlugs": ["men/tops", "men/bottoms"]
            },
            {
                "slug": "men/tops",
                "name": "Men's Tops",
                "level": 1,
                "parentSlug": "men",
                "childrenSlugs": ["men/tops/shirts", "men/tops/jackets"]
            },
            {
                "slug": "men/tops/shirts",
                "name": "Shirts",
                "level": 2,
                "parentSlug": "men/tops",
                "childrenSlugs": []
            }
        ]
    }
}
Copied to your clipboard
{
    "data": {
        "categoryTree": [
            {
                "slug": "men",
                "name": "Men's Clothing",
                "level": 0,
                "parentSlug": null,
                "childrenSlugs": ["men/tops", "men/bottoms"]
            },
            {
                "slug": "men/tops",
                "name": "Men's Tops",
                "level": 1,
                "parentSlug": "men",
                "childrenSlugs": ["men/tops/shirts", "men/tops/jackets"]
            },
            {
                "slug": "men/tops/shirts",
                "name": "Shirts",
                "level": 2,
                "parentSlug": "men/tops",
                "childrenSlugs": []
            }
        ]
    }
}

Example: Retrieve specific category subtree

Query:

query GetSpecificCategorySubtree {
    categoryTree(
        family: "main-catalog"
        slugs: ["men/tops", "men/bottoms"]
        depth: 2
    ) {
        slug
        name
        level
        parentSlug
        childrenSlugs
    }
}
Copied to your clipboard
query GetSpecificCategorySubtree {
    categoryTree(
        family: "main-catalog"
        slugs: ["men/tops", "men/bottoms"]
        depth: 2
    ) {
        slug
        name
        level
        parentSlug
        childrenSlugs
    }
}

Response:

{
    "data": {
        "categoryTree": [
            {
                "slug": "men/tops",
                "name": "Men's Tops",
                "level": 1,
                "parentSlug": "men",
                "childrenSlugs": ["men/tops/shirts", "men/tops/jackets"]
            },
            {
                "slug": "men/tops/shirts",
                "name": "Shirts",
                "level": 2,
                "parentSlug": "men/tops",
                "childrenSlugs": []
            },
            {
                "slug": "men/bottoms",
                "name": "Men's Bottoms",
                "level": 1,
                "parentSlug": "men",
                "childrenSlugs": ["men/bottoms/pants", "men/bottoms/shorts"]
            }
        ]
    }
}
Copied to your clipboard
{
    "data": {
        "categoryTree": [
            {
                "slug": "men/tops",
                "name": "Men's Tops",
                "level": 1,
                "parentSlug": "men",
                "childrenSlugs": ["men/tops/shirts", "men/tops/jackets"]
            },
            {
                "slug": "men/tops/shirts",
                "name": "Shirts",
                "level": 2,
                "parentSlug": "men/tops",
                "childrenSlugs": []
            },
            {
                "slug": "men/bottoms",
                "name": "Men's Bottoms",
                "level": 1,
                "parentSlug": "men",
                "childrenSlugs": ["men/bottoms/pants", "men/bottoms/shorts"]
            }
        ]
    }
}

Example: Retrieve root categories only

Query:

query GetRootCategories {
    categoryTree(family: "main-catalog", depth: 0) {
        slug
        name
        level
        parentSlug
        childrenSlugs
    }
}
Copied to your clipboard
query GetRootCategories {
    categoryTree(family: "main-catalog", depth: 0) {
        slug
        name
        level
        parentSlug
        childrenSlugs
    }
}

Response:

{
    "data": {
        "categoryTree": [
            {
                "slug": "men",
                "name": "Men's Clothing",
                "level": 0,
                "parentSlug": null,
                "childrenSlugs": ["men/tops", "men/bottoms"]
            },
            {
                "slug": "women",
                "name": "Women's Clothing",
                "level": 0,
                "parentSlug": null,
                "childrenSlugs": ["women/tops", "women/bottoms"]
            }
        ]
    }
}
Copied to your clipboard
{
    "data": {
        "categoryTree": [
            {
                "slug": "men",
                "name": "Men's Clothing",
                "level": 0,
                "parentSlug": null,
                "childrenSlugs": ["men/tops", "men/bottoms"]
            },
            {
                "slug": "women",
                "name": "Women's Clothing",
                "level": 0,
                "parentSlug": null,
                "childrenSlugs": ["women/tops", "women/bottoms"]
            }
        ]
    }
}

Use Case Scenarios

Use navigation query with CategoryNavigationView for:

Building responsive navigation components
Creating dropdown menus
Implementing breadcrumb navigation
Mobile menu rendering

Benefits: Optimized performance with caching, depth limits, and lightweight data.

RetailCMS Category Management

Use categoryTree query with CategoryTreeView for:

Category hierarchy management
Building category administration interfaces
Implementing category tree editors
Managing parent-child relationships

Benefits: Complete hierarchy metadata, flexible querying, and detailed relationship information.

Performance Considerations

Navigation Query:
- Heavily cached responses.
- Single database query per family.
- Limited to four levels for performance.
- Excludes heavyweight attributes.
CategoryTree Query:
- Use depth parameter to limit tree traversal.
- Use slugs parameter for targeted queries.
- Ideal for administrative interfaces.
- Provides complete hierarchy metadata.

Use cases

Limitations

Last updated 11/10/2025

Was this helpful?

Yes

Implement Categories on the Storefront

CategoryView2 interface

Interface definition

Fields

Key benefits

Category types

CategoryNavigationView

Type definition

Performance safeguards

CategoryTreeView type

Type definition

Navigation query

Example: Retrieve basic top menu navigation

Example: Retrieve multi-Level menu navigation

CategoryTree query

Example: Retrieve full category tree

Example: Retrieve specific category subtree

Example: Retrieve root categories only

Use Case Scenarios

Storefront Navigation Menu

RetailCMS Category Management

Performance Considerations

Implement Categories on the Storefront

CategoryView2 interface.css-83mclq{margin-left:var(--spectrum-global-dimension-size-100);}

Interface definition.css-jmmyhj{margin-left:var(--spectrum-global-dimension-size-50);}

Fields

Key benefits

Category types

CategoryNavigationView

Type definition

Performance safeguards

CategoryTreeView type

Type definition

Navigation query

Example: Retrieve basic top menu navigation

Example: Retrieve multi-Level menu navigation

CategoryTree query

Example: Retrieve full category tree

Example: Retrieve specific category subtree

Example: Retrieve root categories only

Use Case Scenarios

Storefront Navigation Menu

RetailCMS Category Management

Performance Considerations

CategoryView2 interface

Interface definition