Adobe Commerce only. Learn more

categories query

The categories query returns category data. If the subtree input object is specified, the query returns details about subcategories.

Syntax

type Query {
  categories(ids: [String!], roles: [String!], subtree: Subtree): [CategoryView]
}
Copied to your clipboard
type Query {
  categories(ids: [String!], roles: [String!], subtree: Subtree): [CategoryView]
}

Where subtree is:

input Subtree {
    startLevel: Int!,
    depth: Int!
}
Copied to your clipboard
input Subtree {
    startLevel: Int!,
    depth: Int!
}

If using the subtree input, only one category id can be specified in the query. The subtree object allows you to specify how many levels of subcategories to return. Some sites may have a high number of subcategories, and returning the entire category tree could cause performance issues. It is recommended to keep depth to a maximum of 3 for the same reason.

Endpoints

Testing: https://catalog-service-sandbox.adobe.io/graphql
Production: https://catalog-service.adobe.io/graphql

Required headers

Specify the following HTTP headers to run this query.

Header	Description
`Magento-Customer-Group`	Specify the customer group code for the API request.
`Magento-Environment-Id`	This value is displayed at System > Commerce Services Connector > SaaS Identifier > Data Space ID or can be obtained by running the `bin/magento config:show services_connector/services_id/environment_id` command.
`Magento-Store-Code`	The code assigned to the store associated with the active store view. For example, `main_website_store`.
`Magento-Store-View-Code`	The code assigned to the active store view. For example, `default`.
`Magento-Website-Code`	The code assigned to the website associated with the active store view. For example, `base`.
`X-Api-Key`	Set this value to the unique API key generated for your Commerce environment.

Find the customer group code

The customer group code is the encrypted value of the customer group ID, which determines discounts and tax class for pricing contexts. For B2B implementations, the customer group ID also determines the Shared Catalog context.

Use one of the following codes for a default customer group based on your requirements.

Customer Group	Code
NOT LOGGED IN	`b6589fc6ab0dc82cf12099d1c2d40ab994e8410c`
General	`356a192b7913b04c54574d18c28d46e6395428ab`
Wholesale	`da4b9237bacccdf19c0760cab7aec4a8359010b0`
Retailer	`77de68daecd823babbb58edb1c8e14d7106e83bb`

For merchant-defined groups, the customer group code is the encrypted value of the ID, sha1(<customer_group_id>).

For B2B implementations, the customer group code is the encrypted value of the customer group ID associated with the shared catalog, sha1(<customer_group_id>).

Find a list of available customer group IDs from the Admin (Customers > Customer Groups). For details, see Customer Groups and Shared Catalogs in the Merchant Guide.

Example usage

The following query returns a category tree.

Request:

categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    "depth": 3,
    "startLevel": 1
}) {
    name
    id
    level
    roles
    path
    urlPath
    urlKey
    parentId
    children
    }
Copied to your clipboard
categories(ids: ["11"], roles: ["show_in_menu", "active"], subtree: {
    "depth": 3,
    "startLevel": 1
}) {
    name
    id
    level
    roles
    path
    urlPath
    urlKey
    parentId
    children
    }

Response:

[
   {
      "name":"Bottoms",
      "id":"13",
      "level":3,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/13",
      "urlPath":"men/bottoms-men",
      "urlKey":"bottoms-men",
      "parentId":"11",
      "children":[
         "18",
         "19"
      ]
   },
   {
      "name":"Tops",
      "id":"12",
      "level":3,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12",
      "urlPath":"men/tops-men",
      "urlKey":"tops-men",
      "parentId":"11",
      "children":[
         "14",
         "15",
         "16",
         "17"
      ]
   },
   {
      "name":"Jackets",
      "id":"14",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12/14",
      "urlPath":"men/tops-men/jackets-men",
      "urlKey":"jackets-men",
      "parentId":"12",
      "children":[
      ]
   },
   {
      "name":"Pants",
      "id":"18",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/13/18",
      "urlPath":"men/bottoms-men/pants-men",
      "urlKey":"pants-men",
      "parentId":"13",
      "children":[
      ]
   },
   {
      "name":"Tanks",
      "id":"17",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12/17",
      "urlPath":"men/tops-men/tanks-men",
      "urlKey":"tanks-men",
      "parentId":"12",
      "children":[
      ]
   },
   {
      "name":"Hoodies & Sweatshirts",
      "id":"15",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12/15",
      "urlPath":"men/tops-men/hoodies-and-sweatshirts-men",
      "urlKey":"hoodies-and-sweatshirts-men",
      "parentId":"12",
      "children":[
      ]
   },
   {
      "name":"Shorts",
      "id":"19",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/13/19",
      "urlPath":"men/bottoms-men/shorts-men",
      "urlKey":"shorts-men",
      "parentId":"13",
      "children":[

      ]
   }
]
Copied to your clipboard
[
   {
      "name":"Bottoms",
      "id":"13",
      "level":3,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/13",
      "urlPath":"men/bottoms-men",
      "urlKey":"bottoms-men",
      "parentId":"11",
      "children":[
         "18",
         "19"
      ]
   },
   {
      "name":"Tops",
      "id":"12",
      "level":3,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12",
      "urlPath":"men/tops-men",
      "urlKey":"tops-men",
      "parentId":"11",
      "children":[
         "14",
         "15",
         "16",
         "17"
      ]
   },
   {
      "name":"Jackets",
      "id":"14",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12/14",
      "urlPath":"men/tops-men/jackets-men",
      "urlKey":"jackets-men",
      "parentId":"12",
      "children":[
      ]
   },
   {
      "name":"Pants",
      "id":"18",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/13/18",
      "urlPath":"men/bottoms-men/pants-men",
      "urlKey":"pants-men",
      "parentId":"13",
      "children":[
      ]
   },
   {
      "name":"Tanks",
      "id":"17",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12/17",
      "urlPath":"men/tops-men/tanks-men",
      "urlKey":"tanks-men",
      "parentId":"12",
      "children":[
      ]
   },
   {
      "name":"Hoodies & Sweatshirts",
      "id":"15",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/12/15",
      "urlPath":"men/tops-men/hoodies-and-sweatshirts-men",
      "urlKey":"hoodies-and-sweatshirts-men",
      "parentId":"12",
      "children":[
      ]
   },
   {
      "name":"Shorts",
      "id":"19",
      "level":4,
      "roles":[
         "active",
         "show_in_menu"
      ],
      "path":"1/2/11/13/19",
      "urlPath":"men/bottoms-men/shorts-men",
      "urlKey":"shorts-men",
      "parentId":"13",
      "children":[

      ]
   }
]

Input fields

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]	Defines how many subcategories to return.

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.

Output fields

The categories query returns the CategoryView object, which implements CategoryViewInterface.

CategoryView type

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.

CategoryViewInterface attributes

The CategoryViewInterface returns information about the CategoryView

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.