AdobeDocs · meker12 · May 27, 2026 · Feb 10, 2026 · Mar 30, 2026 · May 27, 2026
diff --git a/src/_includes/graphql/catalog-service/categories.md b/src/_includes/graphql/catalog-service/categories.md
@@ -1,33 +1,35 @@
-The categories query returns the `CategoryView` object, which implements `CategoryViewInterface`.
+The `categories` query returns a list of `CategoryView` objects. Each `CategoryView` describes a category in the catalog tree, including identifiers, hierarchy, URL segments, display sort options, and storefront roles. It implements `CategoryViewInterface` for the shared field set documented below.
 
 ### CategoryView type
 
-Field | Data Type | Description
+Field | Data type | Description
 --- | --- | ---
-`availableSortBy` | [String] | Lists the available sorting methods. Maps to Display Settings > Available Product Listing Sort By.
-`children` | [String!] | A list of subcategories within the category.
-`defaultSortBy` | String | The default sorting method. Maps to Display Settings > Default Product List Sort By.
-`id` | ID! | The category ID.
-`level` | Int | Indicates the depth of the category within the tree.
-`name` | String | The category display name.
-`parentId` | String! | ID of the parent category.
-`path` | String | The path to the category, as a string of category IDs, separated by slashes (/). For example, 1/2/20
-`roles` | [String!]! | A comma-separated list of keywords that are visible only to search engines.
-`urlKey` | String | The part of the URL that identifies the category.
-`urlPath` | String | The URL path for the category.
+`availableSortBy` | [String] | List of available sort by options. For example, `name`, `position`, or `size`. Maps to the category configuration *Display Settings > Available Product List Sort By* in the Commerce Admin.
+`children` | [String!] | List of subcategories by category ID. For example, `123`, `456`, or `789`.
+`defaultSortBy` | String | Default sort by option. For example, `name`, `position`, or `size`. Maps to the category configuration *Display Settings > Available Product List Sort By* in the Commerce Admin.
+`id` | ID! | The category ID. For example, `123`, `456`, or `789`. Maps to Display Settings > Default Product List Sort By in the Admin.
+`level` | Int | Indicates the depth of the category within the tree. The root category is a level 1 category. For example, `men` is level 1, `men/clothing` is level 2, and `men/clothing/shorts` is level 3.
+`name` | String | The category display name. For example, `Electronics`, `Clothing`, or `Books`.
+`parentId` | String! | ID of the parent. For example, `123`, `456`, or `789`.
+`path` | String | The path to the category as a string of category IDs separated by slashes (`/`). For example, `1/2/20`.
+`position` | Int | The position of the category relative to other categories at the same level in the tree. Merchants set this value in the Admin to control display order in storefront navigation. A lower value means the category appears first. For example, `1`, `2`, `3`, or `10`.
+`roles` | [String!]! | Storefront labels assigned during category ingestion that describe visibility and placement. Use them in your storefront logic (for example, show only `active` categories in navigation) or pass matching values in the query `roles` argument to filter results. For example, `active`, `show_in_menu`, `show_on_plp`, or `show_in_search`.
+`urlKey` | String | The part of the URL that identifies the category. For example, `electronics`, `clothing`, or `books`.
+`urlPath` | String | The URL path for the category URL path. For example, `men/bottoms-men` or `men/tops-men/jackets-men`.
 
 ### CategoryViewInterface attributes
 
-The `CategoryViewInterface`  returns information about the CategoryView
+`CategoryViewInterface` defines the shared category metadata that `CategoryView` implements: identity and hierarchy (`id`, `name`, `level`, `path`, `position`), URL segments (`urlKey`, `urlPath`), product listing sort options (`availableSortBy`, `defaultSortBy`), and storefront roles (`roles`). The `CategoryView` type adds tree-navigation fields (`children`, `parentId`) that are not on the interface.
 
 Field | Data Type | Description
 --- | --- | ---
-`availableSortBy` | String | Lists the available sorting methods. Maps to Display Settings > Available Product Listing Sort By.
-`defaultSortBy` | String | The default sorting method. Maps to Display Settings > Default Product List Sort By.
-`id` | ID! | The category ID.
-`level` | Int | Indicates the depth of the category within the tree.
-`name` | String | The category display name.
-`path` | String | The path to the category, as a string of category IDs, separated by slashes (/). For example, 1/2/20
-`roles` | [String!]! | A comma-separated list of keywords that are visible only to search engines.
-`urlKey` | String | The part of the URL that identifies the category.
-`urlPath` | String | The URL path for the category.
+`availableSortBy` | [String] | List of available sort by options. For example, `name`, `position`, or `size`.
+`defaultSortBy` | String | Default sort by option. For example, `name`, `position`, or `size`.
+`id` | ID! | Category ID. For example, `123`, `456`, or `789`.
+`level` | Int | The level of the category. The root category is a level 1 category. For example, `men` is level 1, `men/clothing` is level 2, and `men/clothing/shorts` is level 3.
+`name` | String | Category name. For example, `Electronics`, `Clothing`, or `Books`.
+`path` | String | Category path. For example, `1/2/20` or `/electronics/laptops`.
+`position` | Int | The position of the category relative to other categories at the same level in the tree. For example, `1`, `2`, `3`, or `10`.
+`roles` | [String] | Storefront labels assigned during category ingestion that describe visibility and placement. Use them in your storefront logic (for example, show only `active` categories in navigation) or pass matching values in the query `roles` argument to filter results. For example, `active`, `show_in_menu`, `show_on_plp`, or `show_in_search`.
+`urlKey` | String | Category URL key. For example, `electronics`, `clothing`, or `books`.
+`urlPath` | String | Category URL path. For example, `/electronics/laptops`, `/clothing/shirts`, or `/books/fiction`.
diff --git a/src/pages/graphql/schema/catalog-service/queries/categories.md b/src/pages/graphql/schema/catalog-service/queries/categories.md
@@ -44,7 +44,7 @@ import Headers from '/src/_includes/graphql/catalog-service/headers.md'
 
 <Headers />
 
-###  Find the customer group code
+### Find the customer group code
 
 import CustomerGroupCode from '/src/_includes/graphql/customer-group-code.md'
 
@@ -64,6 +64,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
     "startLevel": 1
 }) {
     name
+    position
     id
     level
     roles
@@ -81,6 +82,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
 [
    {
       "name":"Bottoms",
+      "position":2,
       "id":"13",
       "level":3,
       "roles":[
@@ -98,6 +100,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    },
    {
       "name":"Tops",
+      "position":1,
       "id":"12",
       "level":3,
       "roles":[
@@ -117,6 +120,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    },
    {
       "name":"Jackets",
+      "position":1,
       "id":"14",
       "level":4,
       "roles":[
@@ -132,6 +136,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    },
    {
       "name":"Pants",
+      "position":1,
       "id":"18",
       "level":4,
       "roles":[
@@ -147,6 +152,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    },
    {
       "name":"Tanks",
+      "position":4,
       "id":"17",
       "level":4,
       "roles":[
@@ -162,6 +168,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    },
    {
       "name":"Hoodies & Sweatshirts",
+      "position":2,
       "id":"15",
       "level":4,
       "roles":[
@@ -177,6 +184,7 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    },
    {
       "name":"Shorts",
+      "position":2,
       "id":"19",
       "level":4,
       "roles":[
@@ -198,16 +206,16 @@ categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
 
 Field | Data type | Description
 --- | --- | ---
-`ids` | [String!] | Array of category IDs to return. If using `subtree`, must contain only one ID.
-`roles` | [String!]! |  The list of category roles to be queried.
-`subtree` | [[subtree](#subtree-input)] | Defines the number of sub-levels of categories to return.
+`ids` | [String!] | List of category IDs to retrieve. For example, `123`, `456`, or `789`. If using `subtree`, must contain only one ID.
+`roles` | [String!] | List of roles to filter the categories by. Only categories assigned one of the specified roles are returned. For example, `show_on_plp`, `show_in_pdp`, or `show_in_search`.
+`subtree` | [Subtree](#subtree-input) | Limits the response to a subtree of the category hierarchy. Use `startLevel` to set the topmost level (root = 1) and `depth` to control how many levels of subcategories to include.
 
-### subtree input
+### Subtree input
 
 Field | Data type | Description
 --- | --- | ---
-`startLevel` | [Int!] |The level in the category tree where the search should begin. Minimum of 1.
-`depth` | [Int!]! |  The number of subtrees to return. Values over 3 may impact performance.
+`startLevel` | Int! | The absolute level in the category tree hierarchy to begin retrieving categories from. Level `1` is the root category, level `2` is the first level of children, level `3` is the second, and so on.
+`depth` | Int! | The number of category levels to retrieve below the `startLevel`. For example, a value of `2` returns two levels of subcategories beneath the `startLevel`. Values over 3 may impact performance.
 
 ## Output fields
 

diff --git a/src/pages/graphql/schema/catalog-service/queries/index.md b/src/pages/graphql/schema/catalog-service/queries/index.md
@@ -8,6 +8,10 @@ keywords:
 
 # Catalog Service queries
 
+<InlineAlert variant="info" slots="text"/>
+
+If you are implementing your Commerce catalog using Adobe Commerce Optimizer, see [Retrieve catalog data](https://developer.adobe.com/commerce/services/optimizer/merchandising-services/using-the-api/) in the _Merchandising Services Developer Guide for Commerce Optimizer_.
+
 Catalog Service provides the following queries:
 
 *  [`categories`](categories.md)