diff --git a/spectaql/config-merchandising.yml b/spectaql/config-merchandising.yml index 9a68aeed..5e567e3e 100644 --- a/spectaql/config-merchandising.yml +++ b/spectaql/config-merchandising.yml @@ -115,7 +115,7 @@ introspection: # URL of the GraphQL endpoint to hit if you want to generate the documentation based on live Introspection Query results # NOTE: If not using introspection.url OR servers[], you need to provide x-url below - url: https://na1-sandbox.api.commerce.adobe.com/${TENANT_ID}/graphql # TENANT_ID should be set as an environment variable. This value was previously hardcoded for the Instructor Instance in the Adobe Commerce Optimizer org. + url: https://${API_HOST}/${TENANT_ID}/graphql # TENANT_ID should be set as an environment variable. This value was previously hardcoded for the Instructor Instance in the Adobe Commerce Optimizer org. exclude: excludeMutations: true # diff --git a/spectaql/enhanced-schema.json b/spectaql/enhanced-schema.json index 918cb3a0..8e269da5 100644 --- a/spectaql/enhanced-schema.json +++ b/spectaql/enhanced-schema.json @@ -124,7 +124,7 @@ "args": [ { "name": "family", - "description": "**Required.** The catalog family identifier that determines which catalog's navigation structure to retrieve.\n\n**Typically:** Your store's catalog ID\n\n**Performance Optimizations:**\n- Entire family structure retrieved in single query\n- Heavily cached responses\n- Optimized for frequent navigation requests\n- Minimal database load for menu rendering", + "description": "The product family to retrieve the navigation tree for. For example, clothing, electronics or books", "type": { "name": null, "kind": "NON_NULL", @@ -150,7 +150,7 @@ "args": [ { "name": "family", - "description": "**Required.** The catalog family identifier that determines which catalog's categories to retrieve.\n\n**Typically:** Your store's catalog ID", + "description": "The product family to retrieve the category tree for. Ex: clothing, electronics, books", "type": { "name": null, "kind": "NON_NULL", @@ -162,7 +162,7 @@ }, { "name": "slugs", - "description": "Optional array of specific category slugs to retrieve.\n\n**When Provided:**\n- Returns only specified categories\n- Includes their hierarchical relationships (parents and children)\n- Enables targeted category tree queries\n\n**When Omitted:** All categories in the specified family are returned\n\n**Use Cases:**\n- Fetching specific category branches\n- Retrieving category subtrees\n- Targeted hierarchy queries", + "description": "The slugs of the categories to retrieve the category tree for. Ex: men/clothing/shorts", "type": { "name": null, "kind": "LIST", @@ -174,7 +174,7 @@ }, { "name": "depth", - "description": "Optional maximum depth level to retrieve in the category tree structure.\n\n**Depth Levels:**\n- `0`: Root categories only\n- `1`: Root categories + immediate children\n- `2`: Root + children + grandchildren\n- And so on...\n\n**Benefits:**\n- Improves performance for large category trees\n- Controls response payload size\n- Enables progressive tree loading\n\n**Default:** All available levels are returned if omitted", + "description": "The depth of the category tree to retrieve. For example, depth 1 will retrieve only root categories (categories with level 1), depth 2 will retrieve root categories and their primary children (level 1 & level 2 categories).", "type": { "name": "Int", "kind": "SCALAR", @@ -60286,7 +60286,7 @@ "args": [ { "name": "family", - "description": "**Required.** The catalog family identifier that determines which catalog's navigation structure to retrieve.\n\n**Typically:** Your store's catalog ID\n\n**Performance Optimizations:**\n- Entire family structure retrieved in single query\n- Heavily cached responses\n- Optimized for frequent navigation requests\n- Minimal database load for menu rendering", + "description": "The product family to retrieve the navigation tree for. For example, clothing, electronics or books", "type": { "kind": "NON_NULL", "name": null, @@ -60317,7 +60317,7 @@ "args": [ { "name": "family", - "description": "**Required.** The catalog family identifier that determines which catalog's categories to retrieve.\n\n**Typically:** Your store's catalog ID", + "description": "The product family to retrieve the category tree for. Ex: clothing, electronics, books", "type": { "kind": "NON_NULL", "name": null, @@ -60331,7 +60331,7 @@ }, { "name": "slugs", - "description": "Optional array of specific category slugs to retrieve.\n\n**When Provided:**\n- Returns only specified categories\n- Includes their hierarchical relationships (parents and children)\n- Enables targeted category tree queries\n\n**When Omitted:** All categories in the specified family are returned\n\n**Use Cases:**\n- Fetching specific category branches\n- Retrieving category subtrees\n- Targeted hierarchy queries", + "description": "The slugs of the categories to retrieve the category tree for. Ex: men/clothing/shorts", "type": { "kind": "LIST", "name": null, @@ -60349,7 +60349,7 @@ }, { "name": "depth", - "description": "Optional maximum depth level to retrieve in the category tree structure.\n\n**Depth Levels:**\n- `0`: Root categories only\n- `1`: Root categories + immediate children\n- `2`: Root + children + grandchildren\n- And so on...\n\n**Benefits:**\n- Improves performance for large category trees\n- Controls response payload size\n- Enables progressive tree loading\n\n**Default:** All available levels are returned if omitted", + "description": "The depth of the category tree to retrieve. For example, depth 1 will retrieve only root categories (categories with level 1), depth 2 will retrieve root categories and their primary children (level 1 & level 2 categories).", "type": { "kind": "SCALAR", "name": "Int", @@ -77228,6 +77228,6 @@ } }, "extensions": { - "request-id": "a75167ce-c2a3-4c78-82c4-d114a98c1411" + "request-id": "f42542dc-84eb-472c-8bf5-5d271fcf89e0" } } \ No newline at end of file diff --git a/spectaql/metadata-merchandising.json b/spectaql/metadata-merchandising.json index 0e222cb2..11e483f3 100644 --- a/spectaql/metadata-merchandising.json +++ b/spectaql/metadata-merchandising.json @@ -4103,37 +4103,5 @@ "undocumented": true } } - }, - "FIELD_ARGUMENT": { - "Query": { - "categoryTree": { - "family": { - "documentation": { - "description": "**Required.** The catalog family identifier that determines which catalog's categories to retrieve.\n\n**Typically:** Your store's catalog ID", - "undocumented": false - } - }, - "slugs": { - "documentation": { - "description": "Optional array of specific category slugs to retrieve.\n\n**When Provided:**\n- Returns only specified categories\n- Includes their hierarchical relationships (parents and children)\n- Enables targeted category tree queries\n\n**When Omitted:** All categories in the specified family are returned\n\n**Use Cases:**\n- Fetching specific category branches\n- Retrieving category subtrees\n- Targeted hierarchy queries", - "undocumented": false - } - }, - "depth": { - "documentation": { - "description": "Optional maximum depth level to retrieve in the category tree structure.\n\n**Depth Levels:**\n- `0`: Root categories only\n- `1`: Root categories + immediate children\n- `2`: Root + children + grandchildren\n- And so on...\n\n**Benefits:**\n- Improves performance for large category trees\n- Controls response payload size\n- Enables progressive tree loading\n\n**Default:** All available levels are returned if omitted", - "undocumented": false - } - } - }, - "navigation": { - "family": { - "documentation": { - "description": "**Required.** The catalog family identifier that determines which catalog's navigation structure to retrieve.\n\n**Typically:** Your store's catalog ID\n\n**Performance Optimizations:**\n- Entire family structure retrieved in single query\n- Heavily cached responses\n- Optimized for frequent navigation requests\n- Minimal database load for menu rendering", - "undocumented": false - } - } - } - } } -} \ No newline at end of file +} diff --git a/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md b/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md index fc5c7eb8..be3b5f7f 100644 --- a/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md +++ b/src/pages/optimizer/merchandising-services/categories-storefront-implementation.md @@ -1,7 +1,7 @@ --- title: Implement Categories on the Storefront edition: saas -description: Use the GraphQL category queries to build storefront menus and fetch hierarchical category data with parent-child and level details. +description: Learn to ingest category data, build storefront menus using navigation and categoryTree queries, and retrieve product category context with the products query. keywords: - GraphQL - Services @@ -11,43 +11,25 @@ keywords: # Implement categories on the storefront -Managing categories with Commerce projects that use the Merchandising Services composable catalog data model requires two types of API operations: +Use the following API operations to manage categories for Commerce projects that use the Merchandising Services composable catalog data model: -- Create category data using the `categories` operations available in the [Data Ingestion API](https://developer.adobe.com/commerce/services/reference/rest/#tag/Categories), and using the `products` operations to manage product category assignments. +- Create category data using the `categories` operations available in the [Data Ingestion REST API](https://developer.adobe.com/commerce/services/reference/rest/#tag/Categories), 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](https://developer.adobe.com/commerce/webapi/graphql/merchandising/). +- Retrieve category navigation and hierarchy data using the `navigation` and `categoryTree` queries available in the [Merchandising Services GraphQL API](https://developer.adobe.com/commerce/webapi/graphql/merchandising/). - - -For Commerce sites with an Adobe Commerce as a Cloud Service or Adobe Commerce on Cloud infrastructure backend, use the [Commerce REST API](https://developer.adobe.com/commerce/webapi/rest/) and the [Catalog Service GraphQL API](https://developer.adobe.com/commerce/webapi/graphql/schema/catalog-service/) to manage categories. - -## CategoryViewV2 interface - -The `CategoryViewV2` interface provides a minimal, streamlined set of category fields—`slug` and `name`—optimized for typical storefront display and navigation scenarios. - -### Interface definition - -```graphql -interface CategoryViewV2 { - slug: String! - name: String! -} -``` - -For complete field details, see [`CategoryViewV2`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryViewInterface) in the Merchandising Services GraphQL API reference. +- Retrieve category context for products — such as breadcrumbs — using the `categories` field on product queries in the [Merchandising Services GraphQL API](https://developer.adobe.com/commerce/webapi/graphql/merchandising/). -### Key benefits + -- **Lightweight Design**: Contains essential fields (slug and name) for optimal performance -- **Extensible**: Serves as a base interface for specialized category types +For Commerce sites with an Adobe Commerce as a Cloud Service or an Adobe Commerce on Cloud infrastructure or on-premises backend, manage [categories configuration](https://experienceleague.adobe.com/en/docs/commerce-admin/catalog/categories/categories) from the Commerce Amin, and use the [categories query](https://developer.adobe.com/commerce/webapi/graphql/schema/catalog-service/queries/categories/) available in the [Catalog Service GraphQL API](https://developer.adobe.com/commerce/webapi/graphql/schema/catalog-service/) to manage categories. ## Category types -The `CategoryViewV2` interface is implemented by three specialized types: +The `navigation` query, `categoryTree` query, and `categories` field on product queries each return a different category type, optimized for its specific use case. All three types implement the `CategoryViewV2` interface, which defines the two required fields shared by every category: `slug` and `name`. For complete field details, see [`CategoryViewV2`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryViewInterface) in the Merchandising Services GraphQL API reference. -1. **[CategoryNavigationView](#categorynavigationview-type)** - For menu rendering and navigation -2. **[CategoryProductView](#categoryproductview-type)** - For category data returned with product queries -3. **[CategoryTreeView](#categorytreeview-type)** - For hierarchical category management and rich category pages +1. **[CategoryNavigationView](#categorynavigationview-type)** — For menu rendering and navigation +2. **[CategoryProductView](#categoryproductview-type)** — For category data returned with product queries +3. **[CategoryTreeView](#categorytreeview-type)** — For hierarchical category management and rich category pages ### CategoryNavigationView type @@ -68,16 +50,9 @@ type CategoryNavigationView implements CategoryViewV2 { } ``` -For complete field details, see [`CategoryNavigationView`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryNavigationView) in the Merchandising Services GraphQL API reference. - -See the [Navigation query examples](#navigation-query-examples) section below for example queries and responses using this type. +For complete field details, see `[CategoryNavigationView](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryNavigationView)` in the Merchandising Services GraphQL API reference. -#### 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 +See the [Navigation query examples](#navigation-query-examples) section for example queries and responses using this type. ### CategoryProductView type @@ -104,11 +79,7 @@ The `parents` field is self-referencing—each parent entry is itself a `Categor For complete field details, see [`CategoryProductView`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryProductView) in the Merchandising Services GraphQL API reference. -See the [Products query with categories examples](#products-query-with-categories-examples) section below for example queries and responses using this type. - -#### Performance safeguards - -The `categories` field is optional on product types. Omit it when category data is not needed to avoid unnecessary overhead. +See the [Products query with categories examples](#products-query-with-categories-examples) section for example queries and responses using this type. ### CategoryTreeView type @@ -152,11 +123,39 @@ type CategoryImage { For complete field details, including the [`CategoryMetaTags`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryMetaTags) and [`CategoryImage`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryImage) types, see [`CategoryTreeView`](https://developer.adobe.com/commerce/webapi/graphql/merchandising/#definition-CategoryTreeView) in the Merchandising Services GraphQL API reference. -See the [CategoryTree query examples](#categorytree-query-examples) section below for example queries and responses using this type. +See the [CategoryTree query examples](#categorytree-query-examples) section for example queries and responses using this type. + +## Limitations and considerations + +### Choose the right query for the use case + +- Use the `navigation` query for storefront menus. It is heavily cached, limited to four levels, and returns only the lightweight fields needed for rendering. +- Use the `categoryTree` query when you need full hierarchy metadata, descriptions, images, or SEO fields. +- Use the `categories` field on product queries only when category context (such as breadcrumbs) is needed on a product page. Omit it when it is not needed to avoid unnecessary overhead. + +### Navigation query depth limit + +The `navigation` query returns a maximum of four levels of nested categories. Nesting `children` beyond four levels in your query returns no additional data. Design your category hierarchy and query depth accordingly. + +### `categoryTree` discovery-first behavior + +When `slugs` is omitted from a `categoryTree` query, the `depth` parameter is ignored and only root-level (level 1) categories are returned. This is by design — the query uses a discovery-first pattern that lets clients find category tree entry points before fetching subtrees. To retrieve descendants, always pass `slugs` along with the desired `depth`. + +### Optional fields add overhead + +The `description`, `metaTags`, and `images` fields on `categoryTree` are optional. Exclude them when building navigation or hierarchy views that do not need descriptive content or SEO metadata. + +### Limit `categoryTree` depth + +Pass the `depth` parameter to `categoryTree` to avoid fetching deeper levels than you need. + +### Target specific subtrees + +Pass the `slugs` parameter to `categoryTree` to fetch only the branches you need rather than the entire tree. ## Navigation query examples -Retrieve category navigation data optimized for storefront menu rendering with built-in performance safeguards. +The `navigation` query signature: ```graphql type Query { @@ -164,7 +163,7 @@ type Query { } ``` -The `family` parameter is required and specifies which category family to retrieve. The query returns the full hierarchy for that family in a single request, with a maximum depth of 4 levels. +The `family` parameter is required and specifies which category family to retrieve. The query returns the full hierarchy for that family in a single request. ### Retrieve basic top menu navigation @@ -174,7 +173,7 @@ The `family` parameter is required and specifies which category family to retrie ```graphql query GetTopMenuNavigation { - navigation(family: "Top-menu") { + navigation(family: "top-menu") { slug name children { @@ -277,8 +276,6 @@ Men clothing ## Products query with categories examples -Retrieve category data for products, including breadcrumb ancestors, with optional filtering by category family. - ```graphql type ProductView { categories(family: String): [CategoryProductView] @@ -291,7 +288,7 @@ The `categories` field is available on product types such as `ProductView`. Use -**Request:** +**GraphQL request:** ```graphql query { @@ -325,17 +322,17 @@ query { { "name": "Shorts", "slug": "men/clothes/shorts", - "level": 2, + "level": 3, "parents": [ { "name": "Men", "slug": "men", - "level": 0 + "level": 1 }, { "name": "Clothes", "slug": "men/clothes", - "level": 1 + "level": 2 } ] } @@ -348,8 +345,8 @@ query { The `parents` array provides the full ancestor chain, which you can use to render a breadcrumb path: -```plaintext -Men (level 0) → Clothes (level 1) → Shorts (level 2) +```text +Men (level 1) → Clothes (level 2) → Shorts (level 3) └── product: Red Shorts (M) ``` @@ -393,12 +390,12 @@ query { { "name": "Summer Essentials", "slug": "summer/essentials", - "level": 1, + "level": 2, "parents": [ { "name": "Summer", "slug": "summer", - "level": 0 + "level": 1 } ] } @@ -413,7 +410,7 @@ Without the `family` filter, the response would include categories from all fami ## CategoryTree query examples -Retrieve hierarchical category data in a tree structure with parent-child relationships and level information. +The `categoryTree` query signature: ```graphql type Query { @@ -421,14 +418,16 @@ type Query { } ``` -### Retrieve full category tree +### Retrieve root-level categories + +When called without `slugs`, the query returns only root-level categories. See [`categoryTree` discovery-first behavior](#categorytree-discovery-first-behavior) for details. **Request:** ```graphql -query GetFullCategoryTree { +query GetRootCategories { categoryTree(family: "main-catalog") { slug name @@ -447,38 +446,30 @@ query GetFullCategoryTree { "categoryTree": [ { "slug": "men", - "name": "Men's Clothing", - "level": 0, - "parentSlug": null, - "childrenSlugs": ["men/tops", "men/bottoms"] - }, - { - "slug": "men/tops", - "name": "Men's Tops", + "name": "Men's Category", "level": 1, - "parentSlug": "men", - "childrenSlugs": ["men/tops/shirts", "men/tops/jackets"] + "parentSlug": "", + "childrenSlugs": ["men/clothing"] }, { - "slug": "men/tops/shirts", - "name": "Shirts", - "level": 2, - "parentSlug": "men/tops", - "childrenSlugs": [] + "slug": "women", + "name": "Women's Category", + "level": 1, + "parentSlug": "", + "childrenSlugs": ["women/clothing"] } ] } } ``` -The flat list represents this tree, reconstructed via `parentSlug` and `childrenSlugs`: +The flat list represents the root-level categories and their immediate children. -```plaintext -Men's Clothing (level 0) -├── Men's Tops (level 1) -│ ├── Shirts (level 2) -│ └── Jackets -└── Men's Bottoms +```text +Men's Category (level 1) +└── Men's Clothing (level 2) +Women's Category (level 1) +└── Women's Clothing (level 2) ``` ### Retrieve specific category subtree @@ -491,7 +482,7 @@ Men's Clothing (level 0) query GetSpecificCategorySubtree { categoryTree( family: "main-catalog" - slugs: ["men/tops", "men/bottoms"] + slugs: ["men/clothing", "women/clothing"] depth: 2 ) { slug @@ -510,111 +501,58 @@ query GetSpecificCategorySubtree { "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", + "slug": "men/clothing", + "name": "Men's Clothing", "level": 2, - "parentSlug": "men/tops", - "childrenSlugs": [] + "parentSlug": "men", + "childrenSlugs": ["men/clothing/tops", "men/clothing/bottoms"] }, { - "slug": "men/tops/jackets", - "name": "Jackets", - "level": 2, - "parentSlug": "men/tops", + "slug": "men/clothing/tops", + "name": "Men's Tops", + "level": 3, + "parentSlug": "men/clothing", "childrenSlugs": [] }, { - "slug": "men/bottoms", + "slug": "men/clothing/bottoms", "name": "Men's Bottoms", - "level": 1, - "parentSlug": "men", - "childrenSlugs": ["men/bottoms/pants", "men/bottoms/shorts"] + "level": 3, + "parentSlug": "men/clothing", + "childrenSlugs": [] }, { - "slug": "men/bottoms/pants", - "name": "Pants", + "slug": "women/clothing", + "name": "Women's Clothing", "level": 2, - "parentSlug": "men/bottoms", - "childrenSlugs": [] + "parentSlug": "women", + "childrenSlugs": ["women/clothing/tops", "women/clothing/bottoms"] }, { - "slug": "men/bottoms/shorts", - "name": "Shorts", - "level": 2, - "parentSlug": "men/bottoms", + "slug": "women/clothing/tops", + "name": "Women's Tops", + "level": 3, + "parentSlug": "women/clothing", "childrenSlugs": [] - } - ] - } -} -``` - -The response is a flat list. Each node's `parentSlug` and `childrenSlugs` fields let you reconstruct the tree: - -```plaintext -Men's Tops (level 1) Men's Bottoms (level 1) -├── Shirts (level 2) ├── Pants (level 2) -└── Jackets (level 2) └── Shorts (level 2) -``` - -### Retrieve root categories only - - - -**Request:** - -```graphql -query GetRootCategories { - categoryTree(family: "main-catalog", depth: 0) { - slug - name - level - parentSlug - childrenSlugs - } -} -``` - -**Response:** - -```json -{ - "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"] + "slug": "women/clothing/bottoms", + "name": "Women's Bottoms", + "level": 3, + "parentSlug": "women/clothing", + "childrenSlugs": [] } ] } } ``` -With `depth: 0`, only the top-level roots are returned: +The `depth` parameter counts levels relative to the specified starting slugs, while the `level` field reflects each category's absolute position in the hierarchy based on its slug path. -```plaintext -Men's Clothing (level 0) Women's Clothing (level 0) - childrenSlugs: childrenSlugs: - ├── men/tops ├── women/tops - └── men/bottoms └── women/bottoms - (referenced but not fetched) (referenced but not fetched) +```text +Men's Clothing (level 2) Women's Clothing (level 2) +├── Men's Tops (level 3) ├── Women's Tops (level 3) +└── Men's Bottoms (level 3) └── Women's Bottoms (level 3) ``` ### Retrieve category details with metadata and images @@ -689,54 +627,11 @@ query CategoryTree { } ``` -## Use case scenarios - -### Storefront navigation menu - -Use the `navigation` query with `CategoryNavigationView` for: - -- Building responsive navigation components -- Creating dropdown menus -- Mobile menu rendering - -**Benefits**: Optimized performance with caching, depth limits, and lightweight data. - -### Category landing pages and SEO - -Use the `categoryTree` query with `CategoryTreeView` to build rich category pages: - -- Render category descriptions and hero images on landing pages -- Populate `` tags (`title`, `description`, `keywords`) for SEO -- Display category images with appropriate roles (for example, `BASE` for hero, `THUMBNAIL` for previews) -- Assign custom image roles for merchant-specific layouts - -**Benefits**: Combines hierarchy data with descriptive content, SEO metadata, and images in a single query. - -### Product detail pages and breadcrumbs - -Use the `categories` field on product queries with `CategoryProductView` for: - -- Rendering breadcrumb navigation on product detail pages -- Displaying category badges or tags on product cards -- Filtering or grouping products by category in search results -- Building "Shop by Category" links from a product context - -**Benefits**: The `parents` field provides the full ancestor chain in a single query, eliminating the need for separate category lookups when building breadcrumbs. - -### Retail CMS category management - -Use the `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 +## Query quick reference -- **Choose the right query for the use case.** Use `navigation` for storefront menus—it is heavily cached, limited to four levels, and returns only lightweight fields. Use `categoryTree` when you need full hierarchy metadata, descriptions, or images. -- **Limit tree depth.** Pass the `depth` parameter to `categoryTree` to avoid fetching deeper levels than you need. -- **Target specific subtrees.** Pass the `slugs` parameter to `categoryTree` to fetch only the branches you need rather than the entire tree. -- **Omit optional fields.** The `categories` field on product queries and the `description`, `metaTags`, and `images` fields on `categoryTree` are optional. Exclude them when they are not needed to reduce payload size. +| Use case | Query | Type | +|---|---|---| +| Storefront menus, dropdowns, mobile navigation | `navigation` | `CategoryNavigationView` | +| Category landing pages with SEO metadata and images | `categoryTree` | `CategoryTreeView` | +| Breadcrumbs and category context on product pages | `products` (`categories` field) | `CategoryProductView` | +| Category hierarchy management and CMS administration | `categoryTree` | `CategoryTreeView` | diff --git a/static/graphql-api/merchandising-api/index.html b/static/graphql-api/merchandising-api/index.html index 615b3f91..9374d42d 100644 --- a/static/graphql-api/merchandising-api/index.html +++ b/static/graphql-api/merchandising-api/index.html @@ -257,53 +257,19 @@
Arguments
family - String! - -

Required. The catalog family identifier that determines which catalog's categories to retrieve.

-

Typically: Your store's catalog ID

- + The product family to retrieve the category tree for. Ex: clothing, electronics, books slugs - [String!] - -

Optional array of specific category slugs to retrieve.

-

When Provided:

-
    -
  • Returns only specified categories
    • -
  • Includes their hierarchical relationships (parents and children)
    • -
  • Enables targeted category tree queries
    • -
-

When Omitted: All categories in the specified family are returned

-

Use Cases:

-
    -
  • Fetching specific category branches
    • -
  • Retrieving category subtrees
    • -
  • Targeted hierarchy queries
    • -
- + The slugs of the categories to retrieve the category tree for. Ex: men/clothing/shorts depth - Int - -

Optional maximum depth level to retrieve in the category tree structure.

-

Depth Levels:

-
    -
  • 0: Root categories only
    • -
  • 1: Root categories + immediate children
    • -
  • 2: Root + children + grandchildren
    • -
  • And so on...
    • -
-

Benefits:

-
    -
  • Improves performance for large category trees
    • -
  • Controls response payload size
    • -
  • Enables progressive tree loading
    • -
-

Default: All available levels are returned if omitted

- + The depth of the category tree to retrieve. For example, depth 1 will retrieve only root categories (categories with level 1), depth 2 will retrieve root categories and their primary children (level 1 & level 2 categories). @@ -343,7 +309,7 @@
Query
Variables
{
   "family": "abc123",
-  "slugs": ["abc123"],
+  "slugs": ["xyz789"],
   "depth": 987
 }
@@ -354,14 +320,14 @@
Response
"data": { "categoryTree": [ { - "slug": "xyz789", - "name": "xyz789", - "description": "xyz789", + "slug": "abc123", + "name": "abc123", + "description": "abc123", "metaTags": CategoryMetaTags, "images": [CategoryImage], - "level": 987, - "parentSlug": "xyz789", - "childrenSlugs": ["xyz789"] + "level": 123, + "parentSlug": "abc123", + "childrenSlugs": ["abc123"] } ] } @@ -408,17 +374,7 @@
Arguments
family - String! - -

Required. The catalog family identifier that determines which catalog's navigation structure to retrieve.

-

Typically: Your store's catalog ID

-

Performance Optimizations:

-
    -
  • Entire family structure retrieved in single query
    • -
  • Heavily cached responses
    • -
  • Optimized for frequent navigation requests
    • -
  • Minimal database load for menu rendering
    • -
- + The product family to retrieve the navigation tree for. For example, clothing, electronics or books @@ -451,7 +407,7 @@
Response
"navigation": [ { "slug": "abc123", - "name": "xyz789", + "name": "abc123", "children": [CategoryNavigationView] } ] @@ -581,7 +537,7 @@
Variables
"current_page": 1, "filter": [SearchClauseInput], "page_size": 20, - "phrase": "abc123", + "phrase": "xyz789", "sort": [ProductSearchSortInput] } @@ -596,7 +552,7 @@
Response
"page_info": SearchResultPageInfo, "related_terms": ["xyz789"], "suggestions": ["abc123"], - "total_count": 987, + "total_count": 123, "warnings": [ProductSearchWarning] } } @@ -705,7 +661,7 @@
Response
"data": { "products": [ { - "addToCartAllowed": false, + "addToCartAllowed": true, "inStock": false, "lowStock": true, "attributes": [ProductViewAttribute], @@ -714,20 +670,20 @@
Response
"images": [ProductViewImage], "videos": [ProductViewVideo], "lastModifiedAt": "2007-12-03T10:15:30Z", - "metaDescription": "xyz789", + "metaDescription": "abc123", "metaKeyword": "xyz789", - "metaTitle": "xyz789", - "name": "xyz789", - "shortDescription": "abc123", + "metaTitle": "abc123", + "name": "abc123", + "shortDescription": "xyz789", "inputOptions": [ProductViewInputOption], "sku": "xyz789", "externalId": "abc123", - "url": "xyz789", + "url": "abc123", "urlKey": "xyz789", "links": [ProductViewLink], "categories": [CategoryProductView], "queryType": "xyz789", - "visibility": "xyz789" + "visibility": "abc123" } ] } @@ -834,7 +790,7 @@
Query
Variables
{
   "unitIds": ["abc123"],
-  "currentSku": "xyz789",
+  "currentSku": "abc123",
   "userPurchaseHistory": [PurchaseHistory],
   "userViewHistory": [ViewHistory],
   "cartSkus": ["xyz789"]
@@ -959,7 +915,7 @@ 
Query

               

                 
Variables

                 
{
-  "optionIds": ["abc123"],
+  "optionIds": ["xyz789"],
   "sku": "xyz789"
 }
 

@@ -969,29 +925,29 @@ 
Response

                 
{
   "data": {
     "refineProduct": {
-      "addToCartAllowed": true,
+      "addToCartAllowed": false,
       "inStock": true,
-      "lowStock": false,
+      "lowStock": true,
       "attributes": [ProductViewAttribute],
-      "description": "xyz789",
-      "id": "4",
+      "description": "abc123",
+      "id": 4,
       "images": [ProductViewImage],
       "videos": [ProductViewVideo],
       "lastModifiedAt": "2007-12-03T10:15:30Z",
       "metaDescription": "abc123",
-      "metaKeyword": "abc123",
+      "metaKeyword": "xyz789",
       "metaTitle": "abc123",
       "name": "abc123",
       "shortDescription": "abc123",
       "inputOptions": [ProductViewInputOption],
-      "sku": "xyz789",
-      "externalId": "xyz789",
+      "sku": "abc123",
+      "externalId": "abc123",
       "url": "xyz789",
-      "urlKey": "abc123",
+      "urlKey": "xyz789",
       "links": [ProductViewLink],
       "categories": [CategoryProductView],
       "queryType": "abc123",
-      "visibility": "abc123"
+      "visibility": "xyz789"
     }
   }
 }
@@ -1080,9 +1036,9 @@ 
Query

               

                 
Variables

                 
{
-  "sku": "abc123",
+  "sku": "xyz789",
   "optionIds": ["abc123"],
-  "pageSize": 123,
+  "pageSize": 987,
   "cursor": "xyz789"
 }
 

@@ -1093,7 +1049,7 @@ 
Response

   "data": {
     "variants": {
       "variants": [ProductViewVariant],
-      "cursor": "xyz789"
+      "cursor": "abc123"
     }
   }
 }
@@ -1152,7 +1108,7 @@ 
Example

                 
{
   "attribute": "xyz789",
   "buckets": [Bucket],
-  "title": "xyz789",
+  "title": "abc123",
   "type": "INTELLIGENT"
 }
 

@@ -1263,7 +1219,7 @@ 
Example

                 
{
   "action_type": "BOOST",
   "rule_id": "xyz789",
-  "rule_name": "xyz789"
+  "rule_name": "abc123"
 }
 

               

@@ -1388,11 +1344,6 @@ 
Description

               

             
             

-              

-                
Example

-                
true
-

-              

             

             back to top
           
@@ -1467,7 +1418,7 @@ 
Possible Types

             

               

                 
Example

-                
{"title": "xyz789"}
+                
{"title": "abc123"}
 

               

             

@@ -1529,7 +1480,7 @@ 
Example

                 
{
   "count": 987,
   "id": "4",
-  "path": "xyz789",
+  "path": "abc123",
   "title": "xyz789"
 }
 

@@ -1585,7 +1536,7 @@ 
Possible Types

             

               

                 
Example

-                
{"id": 4}
+                
{"id": "4"}
 

               

             

@@ -1642,9 +1593,9 @@ 
Fields

                 
Example

                 
{
   "url": "abc123",
-  "label": "abc123",
+  "label": "xyz789",
   "roles": ["xyz789"],
-  "customRoles": ["xyz789"]
+  "customRoles": ["abc123"]
 }
 

               
@@ -1750,8 +1701,8 @@ 
Fields

               

                 
Example

                 
{
-  "slug": "xyz789",
-  "name": "abc123",
+  "slug": "abc123",
+  "name": "xyz789",
   "children": [CategoryNavigationView]
 }
 

@@ -1809,8 +1760,8 @@ 
Fields

               

                 
Example

                 
{
-  "name": "xyz789",
-  "slug": "abc123",
+  "name": "abc123",
+  "slug": "xyz789",
   "level": 123,
   "parents": [CategoryProductView]
 }
@@ -1889,8 +1840,8 @@ 
Fields

               

                 
Example

                 
{
-  "slug": "xyz789",
-  "name": "abc123",
+  "slug": "abc123",
+  "name": "xyz789",
   "description": "abc123",
   "metaTags": CategoryMetaTags,
   "images": [CategoryImage],
@@ -2007,16 +1958,16 @@ 
Example

   "availableSortBy": ["abc123"],
   "children": ["xyz789"],
   "defaultSortBy": "xyz789",
-  "id": "4",
-  "level": 987,
-  "name": "abc123",
+  "id": 4,
+  "level": 123,
+  "name": "xyz789",
   "parentId": "abc123",
   "path": "abc123",
-  "roles": ["xyz789"],
-  "urlKey": "xyz789",
-  "urlPath": "xyz789",
-  "count": 123,
-  "title": "xyz789"
+  "roles": ["abc123"],
+  "urlKey": "abc123",
+  "urlPath": "abc123",
+  "count": 987,
+  "title": "abc123"
 }
 

               

@@ -2117,14 +2068,14 @@ 
Possible Types

                 
Example

                 
{
   "availableSortBy": ["xyz789"],
-  "defaultSortBy": "xyz789",
-  "id": "4",
+  "defaultSortBy": "abc123",
+  "id": 4,
   "level": 123,
-  "name": "xyz789",
-  "path": "xyz789",
-  "roles": ["xyz789"],
+  "name": "abc123",
+  "path": "abc123",
+  "roles": ["abc123"],
   "urlKey": "abc123",
-  "urlPath": "abc123"
+  "urlPath": "xyz789"
 }
 

               

@@ -2198,7 +2149,7 @@ 
Possible Types

               

                 
Example

                 
{
-  "slug": "abc123",
+  "slug": "xyz789",
   "name": "abc123"
 }
 

@@ -2429,29 +2380,29 @@ 
family<
                 
Example

                 
{
   "addToCartAllowed": false,
-  "inStock": true,
+  "inStock": false,
   "lowStock": false,
   "attributes": [ProductViewAttribute],
-  "description": "abc123",
+  "description": "xyz789",
   "id": "4",
   "images": [ProductViewImage],
   "videos": [ProductViewVideo],
   "lastModifiedAt": "2007-12-03T10:15:30Z",
-  "metaDescription": "xyz789",
+  "metaDescription": "abc123",
   "metaKeyword": "xyz789",
   "metaTitle": "abc123",
   "name": "abc123",
   "inputOptions": [ProductViewInputOption],
   "options": [ProductViewOption],
   "priceRange": ProductViewPriceRange,
-  "shortDescription": "xyz789",
-  "sku": "xyz789",
+  "shortDescription": "abc123",
+  "sku": "abc123",
   "externalId": "abc123",
-  "url": "abc123",
-  "urlKey": "xyz789",
+  "url": "xyz789",
+  "urlKey": "abc123",
   "links": [ProductViewLink],
   "categories": [CategoryProductView],
-  "queryType": "abc123",
+  "queryType": "xyz789",
   "visibility": "abc123"
 }
 

@@ -2532,8 +2483,8 @@ 
Fields

                 
Example

                 
{
   "attribute": "abc123",
-  "frontendInput": "abc123",
-  "label": "abc123",
+  "frontendInput": "xyz789",
+  "label": "xyz789",
   "numeric": true
 }
 

@@ -2557,7 +2508,7 @@ 
Description

             

               

                 
Example

-                
123.45
+                
987.65
 

               

             

@@ -2608,7 +2559,7 @@ 
Fields

               

                 
Example

                 
{
-  "attribute": "abc123",
+  "attribute": "xyz789",
   "matched_words": ["abc123"],
   "value": "abc123"
 }
@@ -2633,7 +2584,7 @@ 
Description

             

               

                 
Example

-                
4
+                
"4"
 

               

             

@@ -2655,7 +2606,7 @@ 
Description

             

               

                 
Example

-                
987
+                
123
 

               

             

@@ -2770,7 +2721,7 @@ 
Fields

             

               

                 
Example

-                
{"amount": 987.65, "code": "xyz789"}
+                
{"amount": 987.65, "code": "abc123"}
 

               

             

@@ -2898,9 +2849,9 @@ 
Example

   "facets": [Aggregation],
   "items": [ProductSearchItem],
   "page_info": SearchResultPageInfo,
-  "related_terms": ["abc123"],
+  "related_terms": ["xyz789"],
   "suggestions": ["xyz789"],
-  "total_count": 987,
+  "total_count": 123,
   "warnings": [ProductSearchWarning]
 }
 

@@ -2949,7 +2900,7 @@ 
Fields

             

               

                 
Example

-                
{"attribute": "xyz789", "direction": "ASC"}
+                
{"attribute": "abc123", "direction": "ASC"}
 

               

             

@@ -3234,29 +3185,29 @@ 
Possible Types

               

                 
Example

                 
{
-  "addToCartAllowed": false,
+  "addToCartAllowed": true,
   "inStock": false,
-  "lowStock": false,
+  "lowStock": true,
   "attributes": [ProductViewAttribute],
   "description": "xyz789",
-  "id": 4,
+  "id": "4",
   "images": [ProductViewImage],
   "videos": [ProductViewVideo],
   "lastModifiedAt": "2007-12-03T10:15:30Z",
   "metaDescription": "xyz789",
-  "metaKeyword": "abc123",
-  "metaTitle": "abc123",
-  "name": "abc123",
-  "shortDescription": "xyz789",
+  "metaKeyword": "xyz789",
+  "metaTitle": "xyz789",
+  "name": "xyz789",
+  "shortDescription": "abc123",
   "inputOptions": [ProductViewInputOption],
   "sku": "xyz789",
   "externalId": "abc123",
-  "url": "xyz789",
-  "urlKey": "xyz789",
+  "url": "abc123",
+  "urlKey": "abc123",
   "links": [ProductViewLink],
   "categories": [CategoryProductView],
   "queryType": "abc123",
-  "visibility": "xyz789"
+  "visibility": "abc123"
 }
 

               

@@ -3314,8 +3265,8 @@ 
Fields

                 
Example

                 
{
   "label": "abc123",
-  "name": "abc123",
-  "roles": ["abc123"],
+  "name": "xyz789",
+  "roles": ["xyz789"],
   "value": {}
 }
 

@@ -4595,7 +4546,7 @@ 
Example

                 
{
   "label": "xyz789",
   "roles": ["xyz789"],
-  "url": "abc123"
+  "url": "xyz789"
 }
 

               

@@ -4682,16 +4633,16 @@ 
Fields

               

                 
Example

                 
{
-  "id": 4,
-  "title": "abc123",
+  "id": "4",
+  "title": "xyz789",
   "required": true,
-  "type": "xyz789",
+  "type": "abc123",
   "markupAmount": 987.65,
   "suffix": "xyz789",
   "sortOrder": 987,
   "range": ProductViewInputOptionRange,
   "imageSize": ProductViewInputOptionImageSize,
-  "fileExtensions": "abc123"
+  "fileExtensions": "xyz789"
 }
 

               

@@ -4737,7 +4688,7 @@ 
Fields

             

               

                 
Example

-                
{"width": 123, "height": 123}
+                
{"width": 123, "height": 987}
 

               

             

@@ -4782,7 +4733,7 @@ 
Fields

             

               

                 
Example

-                
{"from": 123.45, "to": 123.45}
+                
{"from": 123.45, "to": 987.65}
 

               

             

@@ -4875,7 +4826,7 @@ 
Fields

             

               

                 
Example

-                
{"currency": "AED", "value": 987.65}
+                
{"currency": "AED", "value": 123.45}
 

               

             

@@ -4936,7 +4887,7 @@ 
Fields

               

                 
Example

                 
{
-  "id": 4,
+  "id": "4",
   "multi": false,
   "required": false,
   "title": "abc123",
@@ -5019,9 +4970,9 @@ 
Possible Types

               

                 
Example

                 
{
-  "id": 4,
-  "title": "abc123",
-  "inStock": false
+  "id": "4",
+  "title": "xyz789",
+  "inStock": true
 }
 

               

@@ -5074,8 +5025,8 @@ 
Fields

                 
Example

                 
{
   "id": 4,
-  "title": "abc123",
-  "inStock": true
+  "title": "xyz789",
+  "inStock": false
 }
 

               

@@ -5143,11 +5094,11 @@ 
Fields

                 
Example

                 
{
   "id": 4,
-  "isDefault": true,
+  "isDefault": false,
   "product": SimpleProductView,
   "quantity": 123.45,
-  "title": "xyz789",
-  "inStock": true
+  "title": "abc123",
+  "inStock": false
 }
 

               

@@ -5209,11 +5160,11 @@ 
Fields

               

                 
Example

                 
{
-  "id": 4,
+  "id": "4",
   "title": "xyz789",
   "type": "TEXT",
-  "value": "abc123",
-  "inStock": true
+  "value": "xyz789",
+  "inStock": false
 }
 

               

@@ -5495,7 +5446,7 @@ 
Fields

             

               

                 
Example

-                
{"gte": 987.65, "lt": 123.45}
+                
{"gte": 123.45, "lt": 987.65}
 

               

             

@@ -5590,7 +5541,7 @@ 
Fields

                 
Example

                 
{
   "variants": [ProductViewVariant],
-  "cursor": "abc123"
+  "cursor": "xyz789"
 }
 

               

@@ -5649,8 +5600,8 @@ 
Example

                 
{
   "preview": ProductViewImage,
   "url": "xyz789",
-  "description": "xyz789",
-  "title": "abc123"
+  "description": "abc123",
+  "title": "xyz789"
 }
 

               
@@ -5805,10 +5756,10 @@ 
Fields

               

                 
Example

                 
{
-  "count": 987,
-  "from": 987.65,
+  "count": 123,
+  "from": 123.45,
   "title": "abc123",
-  "to": 123.45
+  "to": 987.65
 }
 

               

@@ -5889,10 +5840,10 @@ 
Example

   "pageType": "abc123",
   "productsView": [ProductView],
   "storefrontLabel": "xyz789",
-  "totalProducts": 123,
-  "typeId": "abc123",
+  "totalProducts": 987,
+  "typeId": "xyz789",
   "unitId": "abc123",
-  "unitName": "abc123"
+  "unitName": "xyz789"
 }
@@ -5988,7 +5939,11 @@
Fields
Example
- 
{"count": 987, "id": 4, "title": "abc123"}
+                
{
+  "count": 123,
+  "id": "4",
+  "title": "abc123"
+}
@@ -6063,7 +6018,7 @@
Example
"attribute": "xyz789", "contains": "xyz789", "eq": "xyz789", - "in": ["xyz789"], + "in": ["abc123"], "range": SearchRangeInput, "startsWith": "xyz789" } @@ -6113,7 +6068,7 @@
Fields
Example
- 
{"from": 987.65, "to": 123.45}
+                
{"from": 987.65, "to": 987.65}
@@ -6163,7 +6118,7 @@
Fields
Example
- 
{"current_page": 123, "page_size": 987, "total_pages": 987}
+                
{"current_page": 123, "page_size": 123, "total_pages": 123}
@@ -6386,7 +6341,7 @@
family<
Example
{
   "addToCartAllowed": true,
-  "inStock": false,
+  "inStock": true,
   "lowStock": false,
   "attributes": [ProductViewAttribute],
   "description": "abc123",
@@ -6395,20 +6350,20 @@ 
Example

   "videos": [ProductViewVideo],
   "inputOptions": [ProductViewInputOption],
   "lastModifiedAt": "2007-12-03T10:15:30Z",
-  "metaDescription": "abc123",
+  "metaDescription": "xyz789",
   "metaKeyword": "xyz789",
   "metaTitle": "xyz789",
   "name": "xyz789",
   "price": ProductViewPrice,
-  "shortDescription": "xyz789",
+  "shortDescription": "abc123",
   "sku": "xyz789",
-  "externalId": "abc123",
+  "externalId": "xyz789",
   "url": "abc123",
-  "urlKey": "xyz789",
+  "urlKey": "abc123",
   "links": [ProductViewLink],
   "categories": [CategoryProductView],
   "queryType": "abc123",
-  "visibility": "abc123"
+  "visibility": "xyz789"
 }
@@ -6515,9 +6470,9 @@
Fields
Example
{
   "attribute": "xyz789",
-  "frontendInput": "xyz789",
+  "frontendInput": "abc123",
   "label": "abc123",
-  "numeric": true
+  "numeric": false
 }
@@ -6569,8 +6524,8 @@
Fields
Example
{
-  "max": 123.45,
-  "min": 123.45,
+  "max": 987.65,
+  "min": 987.65,
   "title": "abc123"
 }
@@ -6594,7 +6549,7 @@
Description
Example
- 
"abc123"
+                
"xyz789"
@@ -6708,7 +6663,7 @@
Fields
Example
{
   "date": "2007-12-03T10:15:30Z",
-  "sku": "xyz789"
+  "sku": "abc123"
 }
@@ -6760,7 +6715,7 @@
Fields
Example
{
   "dateTime": "2007-12-03T10:15:30Z",
-  "sku": "xyz789"
+  "sku": "abc123"
 }