Skip to Content

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

FieldTypeNullableDescriptionRelationship
productsCountIntYesThe total number of products in this product group, not affected by filters.None
seoDescriptionStringYesSEO meta description for this product group.None
seoTitleStringYesSEO meta title for this product group.None
seoKeywordsStringYesSEO meta keywords for this product group.None
idIntYesUnique identifier for this product group.None
titleStringYesDisplay name/title of this product group.None
handleStringYesHandle (unique string or id) for this product group.None
descriptionStringYesHTML-formatted description of this product group.None
imageStringYesImage URL for this product group.None
productGroups[ProductGroup]YesChild product groups (subcategories) for this product group.Self-referential
parentProductGroupYesParent product group if it exists, otherwise null.Self-referential
breadcrumbs[ProductGroup]YesBreadcrumb trail (list of parent product groups) for this product group.Self-referential
filters[Filter]YesAvailable filters for this product group, or null if none are set.Related to Filter type
productsProductConnectionYesConnection to products belonging to this product group.Related to ProductConnection

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 } } } }
  • 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.
Last updated on