Building the Product Catalogue Page using Propeller Commerce GraphQL API

Building a well-structured, user-friendly product catalogue page is a key feature of any e-commerce platform. It allows customers to browse categories, filter products, and view details effortlessly. Propeller Commerce offers a robust GraphQL API that makes it easy to fetch product data, display categories, implement filtering, and more. This tutorial will walk you through how to create a catalogue and product page using the Propeller Commerce GraphQL API.

Why It’s Important

A catalogue page is the heart of an ordering portal, providing a smooth & fast interface for customers to browse and search products, view inventory and choose product variants (like size and color). An effective product catalogue enhances user experience and drives sales.

Key Topics Covered

Fetching product data via GraphQL queries
Fetching hierarchical categories
Filtering Products by Attributes and Search Functionality*
Implementing pagination
Displaying product inventory
Handling product variants (clusters in Propeller Commerce)
Advanced filtering (order lists, bundles, etc.)

Let’s dive into each of these areas.

1. Fetching Product Data via GraphQL Queries

To start, you’ll need to fetch the products data using the products query below.

Query Example: Fetching Products

query GetProducts($language: String) {
  products {
    items {
      ... on Product {
        names(language: $language) {
          value
        }
        category {
          categoryId
          name(language: $language) {
            value
          }
        }
        productId
        manufacturer
        minimumQuantity
        price {
          gross
          net
        }
        sku
        slugs(language: $language) {
          value
        }
        media {
          images(search: { sort: ASC, offset: 1 }) {
            items {
              alt(language: $language) {
                value
              }
              imageVariants(
                input: {
                  transformations: {
                    name: "small"
                    transformation: {
                      width: 50
                      height: 50
                      fit: BOUNDS
                      format: WEBP
                    }
                  }
                }
              ) {
                url
              }
            }
          }
        }
      }
    }
  }
}

Query Breakdown

names(language: $language): Fetches the product's localized name in a specific language
category: Retrieves the product's category information, including categoryId and localized category name
productId: The unique identifier for the product
manufacturer: Provides the product's manufacturer
minimumQuantity: Specifies the minimum quantity that must be ordered for this product
price: Contains two subfields:
- net: Total price including taxes
- gross: Price excluding taxes
sku: The product's Stock Keeping Unit
slugs(language: $language): Retrieves the product’s URL-friendly slug in a specific language
media.images: This field fetches product images. The images can be filtered, sorted, and transformed (resized, formatted, etc.) through parameters like transformations to optimize them for display on different devices
media.images.items.alt(language: $language): Retrieves the localized alternative text for images
media.images.items.url: Image's URL

2. Fetching Hierarchical Categories

Many e-commerce platforms have hierarchical category structures (e.g., Men > Shoes > Sneakers). With Propeller Commerce, you can represent these using the parent field in the getCategories query. This allows you to display categories as a nested structure.

Query Example: Fetching Category Hierarchies

query GetCategories($filter: CategoryFilterInput, $language: String) {
  categories(filter: $filter) {
    page
    itemsFound
    offset
    items {
      ... on Category {
        categoryId
        categoryPath {
          categoryId
          name(language: $language) {
            language
            value
          }
        }
        name(language: $language) {
          language
          value
        }
        parent {
          categoryId
          name(language: $language) {
            language
            value
          }
        }
      }
    }
  }
}

You can build a nested category navigation from this data, which helps users drill down into specific product types.

The CategoryFilterInput input can be used to filter the categories by:

categoryId: Find categories by one or more category IDs
language: The language to use when searching categories by name or slug. If omitted, the category's default language is used
name: Find categories by name
offset: The number of categories to return per page
page: The page number to return in pagination
parentCategoryId: Find categories by one or more parent category IDs
slug: Find categories by one or more slugs

You can build a category details page using the following more detailed query.

Query Example: Fetching Category Hierarchies

query GetCategoryDetails($slug: String, $language: String) {
  category(slug: $slug) {
    categoryId
    name {
      language
      value
    }
    parent {
      categoryId
      name {
        language
        value
      }
    }
    description {
      language
      value
    }
    shortDescription {
      language
      value
    }
    slug(language: $language) {
      value
    }
    categoryPath {
      categoryId
      name(language: $language) {
        value
      }
    }
  }
}

Query breakdown:

description: Retrieves the category's localized description
shortDescription: Retrieves the category's localized shortDescription
categoryPath: Retrieves the category hierarchy which makes it easy to build a breadcrumb
slug: Retrieves the category’s URL-friendly slug in a specific language

3. Filtering Products by Attributes and Search Functionality

Filtering is an essential feature that lets customers find products based on attributes like price, size, color, etc. You can use filters directly in the products query. Propeller Commerce supports advanced filtering, offering a range of options. You can use static product fields, or custom product data defined via product attributes.

Let's first write a product query that retrieves available attributes:

Query Example: Product Attributes

query CatalogQuery($input: ProductSearchInput) {
  products(input: $input) {
    page
    itemsFound
    pages
    offset
    filters(input: { isPublic: true, isSearchable: true }) {
      attributeDescription {
        name
        descriptions {
          language
          value
        }
      }
      decimalRangeFilter {
        max
        min
      }
      textFilters {
        count
        value
        countTotal
        countActive
        isSelected
      }
      type
    }
    items {
      ... on Product {
        productId
      }
    }
  }
}

Retrieved filters, either range or text filters, can then be used to filter products via ProductSearchInput.rangeFilters and ProductSearchInput.textFilters. Below is a breakdown of some interesting product search fields available in ProductSearchInput.

categoryId: Product unique category identifier in Propeller Commerce
containerPathSlugs: Parent path slugs
containerSlugs: Parent slugs
EANCodes: Filter based on product EAN codes
hidden: Filter based on whether product is hidden or not
productIds: Product unique ID in Propeller Commerce catalogue
manufacturerCodes: Product manufacturer codes
manufacturers: Product manufacturer
price: Product price
- from: Price from
- to: Price to
rangeFilters: Product attribute range filters
- from: Value from
- to: Value to
- exclude: Indicates whether to include or exclude
- id: Attribute ID. Either provide id or name
- name: Attribute name. Either provide id or name
term: Search term. You can indicate which fields will be searched
searchFields: term will be used to search through this array of fields, such as sku, name, supplier code, description, etc. Check documentation for the list of available fields
skus: Product SKUs
statuses: Product status
supplierCodes: Product supplier codes
suppliers: Product suppliers
tags: Product tags
textFilters: Product attribute text filters
sortInputs: Sort results based on Product sort fileds, surch as sku, name, relevance, etc. Check documentation for the list of available fields.

The following query retrieves products by search term, price and color attribute:

Query Example: Filtering Products

query CatalogQuery($input: ProductSearchInput) {
  products(
    input: {
      term: "car"
      price: { to: 30000 }
      textFilters: [{ name: "COLOR", values: ["red", "blue"] }]
    }
  ) {
    page
    itemsFound
    pages
    offset
    items {
      ... on Product {
        productId
      }
    }
  }
}

You can also filter by other fields. For the full list, check Propeller Commerce API documentation.

4. Implementing Pagination

Pagination is crucial when dealing with large product catalogues, allowing users to browse a portion of products at a time. Propeller Commerce offers built-in pagination in the products query.

Query Example: Pagination

query GetProducts($page: Int, $offset: Int) {
  products(input: { page: $page, offset: $offset }) {
    items {
      ... on Product {
        productId
      }
    }
    itemsFound
    start
    end
    page
    pages
  }
}

You can control the number of products displayed per page using offset and the current page via page field. Total number of items can be retrieved via itemsFound field. Fields start and end indicate the start and end position of the current page. Pagination is implemented in the same manner across multiple queries in Propeller Commerce, including categories query.

5. Displaying Product Inventory

Displaying stock levels is key for an ordering portal. Propeller Commerce allows you to fetch inventory data through the products and product queries.

Query Example: Displaying Product Inventory

query GetProductInventory {
  products {
    items {
      ... on Product {
        productId
        inventory {
          totalQuantity
        }
      }
    }
  }
}

This query returns total available quantity, so you can inform customers if a product is in stock or not. Additionally, you can check the balance of products per different locations i.e. warehouses. Check Propeller Commerce API documentation for more details.

6. Handling Product Variants (Clusters)

Product variants (e.g., size, color) are referred to as "clusters" in Propeller Commerce. Managing clusters effectively allows you to display all the variations of a product, giving customers flexibility in their choices. Both products and clusters are a catalogue item. When using the products query, items in the result can be either a product or a cluster. Orderable cluster choices are regular products, but are grouped in clusters to avoid duplicating images, descriptions, etc.

The products query allows you to search specifically for either products or clusters by utilizing the ProductSearchInput.class parameter with the values PRODUCT or CLUSTER. When presenting clusters on a catalogue page, you can display information such as prices, images, inventory, etc. from the default product within the cluster.

Query Example: Handling product and clusters catalogue results

query GetProducts($language: String) {
  products {
    items {
      ... on Product {
        names(language: $language) {
          value
        }
        category {
          categoryId
          name(language: $language) {
            value
          }
        }
        productId
        manufacturer
        minimumQuantity
        price {
          gross
          net
        }
        sku
        slugs(language: $language) {
          value
        }
        media {
          images(search: { sort: ASC, offset: 1 }) {
            items {
              alt(language: $language) {
                value
              }
              imageVariants(
                input: {
                  transformations: {
                    name: "small"
                    transformation: {
                      width: 50
                      height: 50
                      fit: BOUNDS
                      format: WEBP
                    }
                  }
                }
              ) {
                url
              }
            }
          }
        }
      }
      ... on Cluster {
        names(language: $language) {
          value
        }
        sku
        category {
          categoryId
          name(language: $language) {
            value
          }
        }
        defaultProduct {
          names(language: $language) {
            value
          }
          productId
          manufacturer
          minimumQuantity
          price {
            gross
            net
          }
          sku
          slugs(language: $language) {
            value
          }
          media {
            images(search: { sort: ASC, offset: 1 }) {
              items {
                alt(language: $language) {
                  value
                }
                imageVariants(
                  input: {
                    transformations: {
                      name: "small"
                      transformation: {
                        width: 50
                        height: 50
                        fit: BOUNDS
                        format: WEBP
                      }
                    }
                  }
                ) {
                  url
                }
              }
            }
          }
        }
      }
    }
  }
}

7. Advanced Filtering: Order Lists, Bundles

In some cases, you might need to apply more advanced filtering. For example, fetching specific bundles or products associated with certain order lists is common in B2B commerce. Bundles are groups of products that have a special price when bought together. The Propeller API allows for these advanced use cases as well.

This query allows you to fetch only bundle products.

Query Example: Fetching Bundles

query GetProductBundles {
  products(input: { hasBundle: Y }) {
    items {
      ... on Product {
        productId
      }
    }
    itemsFound
  }
}

This query allows you to fetch only products in certain order lists.

Query Example: Fetching Order list Products

query GetOrderListProducts {
  products(input: { applyOrderlists: true, orderlistIds: [1, 3, 678] }) {
    items {
      ... on Product {
        productId
      }
    }
    itemsFound
  }
}

Conclusion

By utilizing the Propeller Commerce GraphQL API, you can easily create a dynamic and user-friendly product catalogue page that includes products, categories, filters, pagination, inventory status, product variants (clusters) and more. Each of these features enhances the overall user experience, helping your customers find the right products efficiently.

With this approach, building a powerful catalogue page becomes straightforward and highly customizable based on your specific needs.

For more information on the GraphQL schema and available queries, visit the Propeller Commerce API documentation.

Building the Product Catalogue Page using Propeller Commerce GraphQL API

Why It’s Important​

Key Topics Covered​

1. Fetching Product Data via GraphQL Queries​

2. Fetching Hierarchical Categories​

3. Filtering Products by Attributes and Search Functionality​

4. Implementing Pagination​

5. Displaying Product Inventory​

6. Handling Product Variants (Clusters)​

7. Advanced Filtering: Order Lists, Bundles​

Conclusion​