ProductGroup

Represents a product group in the store, including its metadata, SEO fields, relationships, and available filters for GraphQL queries.

Type Definition

type ProductGroup {
  productsCount: Int
  seoDescription: String
  seoTitle: String
  seoKeywords: String
  id: Int
  title: String
  handle: String
  description: String
  image: String
  productGroups: [ProductGroup]
  parent: ProductGroup
  breadcrumbs: [ProductGroup]
  filters: [Filter]
  products: ProductConnection
}

Fields

Relationships

• productGroups: Represents child product groups (subcategories) of this product group, allowing hierarchical navigation.
• parent: Points to the parent product group, enabling traversal up the category tree.
• breadcrumbs: Provides a list of ancestor product groups forming the breadcrumb trail for UI navigation.
• filters: Lists available filters applicable to this product group, useful for refining product queries.
• products: A connection to the products within this product group, supporting pagination and filtering.

Usage Examples

Basic Query

Fetch basic metadata and SEO information about a product group by its ID:

query {
  productGroup(id: 12345) {
    id
    title
    handle
    seoTitle
    seoDescription
    productsCount
  }
}

Field Selection

Retrieve detailed information including description, image, and SEO keywords:

query {
  productGroup(id: 12345) {
    title
    description
    image
    seoKeywords
  }
}

Nested Queries

Access child product groups and their titles, as well as the breadcrumb trail for navigation:

query {
  productGroup(id: 12345) {
    title
    productGroups {
      id
      title
      handle
    }
    breadcrumbs {
      id
      title
    }
  }
}

Traverse the products connection to get product details with pagination:

query {
  productGroup(id: 12345) {
    products(first: 5) {
      edges {
        node {
          id
          title
          handle
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Filtering and Sorting

Filter products within a product group by available filters and sort by title ascending:

query {
  productGroup(id: 12345) {
    filters {
      id
      name
      type
      options {
        id
        label
      }
    }
    products(first: 10, filter: { priceRange: { min: 10, max: 100 } }, sort: { field: TITLE, direction: ASC }) {
      edges {
        node {
          id
          title
          price
        }
      }
    }
  }
}

Note: The exact filter input structure depends on the Filter type schema.

Implements

The ProductGroup type does not explicitly implement any interfaces.

Connections

• products: This field returns a ProductConnection object, which supports pagination through edges and pageInfo. Use arguments such as first, after, last, and before to paginate through products.

Example of paginating products:

query {
  productGroup(id: 12345) {
    products(first: 10, after: "cursorString") {
      edges {
        node {
          id
          title
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

Related Types

• ProductGroup (self-referential for parent, children, and breadcrumbs)
• Filter (used in the filters field to represent available filters)
• ProductConnection (used in the products field for product listings)

Best Practices

• Use the id field to uniquely identify product groups in queries.
• Leverage the filters field to dynamically build UI filter options for product listings.
• Use pagination arguments on the products connection to efficiently load products in batches.
• When displaying navigation, use breadcrumbs to provide users with context and easy traversal.
• Avoid querying large nested structures unnecessarily to maintain query performance.
• Cache frequently requested product group metadata to reduce repeated network calls.

Notes

• All fields in ProductGroup are optional and may return null if data is not available.
• The productsCount field reflects the total number of products in the group without applying any filters.
• The API currently requires no authentication, but this may change in future versions.
• Use appropriate error handling in your client to manage cases where fields return null or data is missing.
• The description field contains HTML-formatted content; sanitize or render appropriately in your UI.
• The image field provides a URL string; ensure your application handles image loading and fallback gracefully.
• Filtering and sorting capabilities depend on the schema of the related Filter and ProductConnection types; consult their documentation for details.