Working with Categories

Fetching and working with catalog data is a fundamental task for a headless storefront. Let’s start with an examination of GraphQL queries for fetching categories and their products. These queries will typically power a storefront’s main navigation and product listing pages.

The Category Tree

The category tree is the structure that organizes all categories within a storefront. A storefront can include multiple categories, along with subcategories nested beneath top-level ones. Its primary purpose is to support site navigation, helping customers quickly filter products and browse the specific category they’re interested in.

Category Tree Main Navigation

Like other queries we have looked at, you can query for basic category information such as entityId, name, etc., but the categoryTree query has the capability of giving information about the hierarchical relationship between categories. Other information that you would want to include in your categoryTree query includes:

• productCount - returns the number of products that are assigned to each category, but does not include products in each sub-category
• hasChildren - tells you if there is a sub-category
• children - a recursive field that allows you to drill down into different levels of the category tree
• path - shows you the URL path for the category page

The example query below will return a list of category information as well as their sub-categories and URL paths. As you dig into sub-categories, the path field will results will reflect the navigation of the category tree.

query GetCategoryTree {
  site {
    categoryTree {
      ... CategoryFields
      children {
        ... CategoryFields
      }
    }
  }
}
fragment CategoryFields on CategoryTreeItem {
    entityId
    name
    hasChildren
    path
}

You can continue retrieving subcategory (child) information by nesting additional levels of the children field in your query. Unlike previous examples, where cursor values had to be added in the edges field and data fields specified as nodes, the categoryTree query does not require edges or nodes to access subcategory data.

For example, you want to see three levels of categories in your categoryTree query. You will need to write a query like the one below:

query GetCategoryTree {
  site {
    categoryTree {
      ... CategoryFields
      children {
        ... CategoryFields
        children {
          ... CategoryFields
        }
      }
    }
  }
}
fragment CategoryFields on CategoryTreeItem {
    entityId
    name
    hasChildren
    path
}

Another children field and the information we need about the sub-category was simply added to the query.

You can include as many children fields as needed in a query, but it’s useful to know where the category tree ends. The hasChildren field eliminates the need to guess by returning a simple true or false value. This response indicates whether a category or subcategory has further levels, helping you quickly decide if you need to continue expanding the query.

Giving a Category Tree Query a Starting Point

If you want to search for a specific segment of the whole category tree, you can do so by specifying a root category in the categoryTree query.

For example, you only want a list of sub-categories under a specific category. The query below will use given categoryId as the root category and only show you the sub-categories that exist underneath. This query will also return the path field, which will give you information about the hierarchical relationship between the main category and sub-categories.

query RootCategory($rootCategory: Int!) {
  site {
    categoryTree(rootEntityId: $rootCategory) {
      entityId
      name
      productCount
      hasChildren
      path
      children {
        entityId
        name
        productCount
        hasChildren
        path
      }
    }
  }
}

You must include the children field if you want the response to show the next level of categories. The rules that were discussed in the previous section apply to this query too: the children field is the only way to view sub-categories with this query, and you can ask for as many levels of children as you feel is necessary.

The Category Page

A category page displays products that are assigned to a specified category. This is different than a product detail page because it only contains a list of product objects, not all of the product details.

You can utilize the GraphQL Storefront API to retrieve information about the category such as:

• id
• entityId
• name
• description
• seo

Example query for a typical category page:

query getCategory($categoryId: Int!){
  site{
    category(entityId:$categoryId){
      id
      entityId
      name
      seo{
        pageTitle
        metaDescription
        metaKeywords
      }
    }
  }
}

The example query above will only return the requested information for the specified category. This information would be useful if you need general information about a category and nothing else.

In addition to the category information listed above, other fields available for this type of query include defaultImage and metafields. These two fields work similarly to the fields that we looked at in the previous lesson working with the PDP.

Query for Products in a Category

To take the category query a step further, you can add a products field to obtain a list of product objects that are assigned to the category. This is exactly like the query we covered in the previous lesson, but it is nested under the category field in the query.

In the previous lesson, you queried for a general product list on the storefront beginning with a specific product entityId. The difference with the example query below is that it is querying for a list of products within a specific category on the storefront. The products field in this category query works the same way as the query you used for the product detail page. The product list that is returned is a cursor list that you can use to set a starting/ending point for the returned list of products. Additional fields are also available under node to give you data about each product object that appears on the category page.

query GetCategoryProducts($categoryIds: Int!){
  site{
    category(entityId:$categoryIds){
      entityId
      name
      description
      products{
        collectionInfo{
          totalItems
        }
        edges{
          node{
            entityId
            sku
            name
            description
          }
        }
      }
    }
  }
}

There is one additional feature that querying for a product list on a category page offers. Since it is fetching information about a category page, the ability to sort products is now an available argument that can be added to the query. This allows the GraphQL Storefront API to fetch a more defined list of products. You can use the sortBy argument to sort the returned product list by default, price, alphabetically, best selling, reviews, featured products, and newest products.

The example query below shows the same query we used to look at a category page’s product list, but the product list will now be sorted by price (highest to lowest).

query GetCategoryProducts($categoryIds: Int!) {
  site {
    category(entityId: $categoryIds) {
      entityId
      name
      description
      products(sortBy: HIGHEST_PRICE) {
        collectionInfo {
          totalItems
        }
        edges {
          node {
            entityId
            sku
            name
            description
          }
        }
      }
    }
  }
}

When it comes to versatility of product lists, this type of query will return more information than only asking for product details. However, the query is still quite defined by category information > product information. You can use certain fields to help define the list but if your storefront would benefit from faceted search, the search query would be a better option.