productGroup

Retrieve a single product group by its unique ID. This query returns detailed information about the product group, including metadata, SEO fields, hierarchical relationships, available filters, and product listings.

Query Structure


query {
  productGroup(id: ID!) {
    productsCount
    seoDescription
    seoTitle
    seoKeywords
    id
    title
    handle
    description
    image
    productGroups {
      id
      title
      handle
    }
    parent {
      id
      title
      handle
    }
    breadcrumbs {
      id
      title
      handle
    }
    filters {
      id
      name
      type
      values
    }
    products {
      edges {
        node {
          id
          title
          price
          available
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Arguments

Argument	Type	Description	Required	Default Value
id	ID!	The unique identifier of the product group to retrieve	Yes	N/A

Return Type

ProductGroup

Represents a product group in the store, including its metadata, SEO fields, hierarchical relationships, available filters, and associated products.

Field	Type	Description
productsCount	Int	Total number of products in this product group, unaffected by filters.
seoDescription	String	SEO meta description for this product group.
seoTitle	String	SEO meta title for this product group.
seoKeywords	String	SEO meta keywords for this product group.
id	Int	Unique identifier for this product group.
title	String	Display name/title of this product group.
handle	String	Handle (unique string or ID) for this product group.
description	String	HTML-formatted description of this product group.
image	String	Image URL representing this product group.
productGroups	[ProductGroup]	Child product groups (subcategories) of this product group.
parent	ProductGroup	Parent product group if it exists; otherwise, false.
breadcrumbs	[ProductGroup]	Breadcrumb trail listing parent product groups for navigation.
filters	[Filter]	Available filters for this product group, or null if none are set.
products	ProductConnection	Connection object containing products within this product group.

Examples

Basic Query


query {
  productGroup(id: 12345) {
    id
    title
    description
    productsCount
  }
}

Advanced Query


query {
  productGroup(id: 12345) {
    id
    title
    seoTitle
    seoDescription
    seoKeywords
    handle
    description
    image
    productGroups {
      id
      title
      handle
    }
    parent {
      id
      title
      handle
    }
    breadcrumbs {
      id
      title
      handle
    }
    filters {
      id
      name
      type
      values
    }
    products {
      edges {
        node {
          id
          title
          price
          available
        }
      }
      pageInfo {
        hasNextPage
        hasPreviousPage
      }
    }
  }
}

Field Selection


query {
  productGroup(id: 12345) {
    title
    productsCount
    filters {
      id
      name
      type
      values
    }
    products {
      edges {
        node {
          id
          title
          price
          available
        }
      }
    }
  }
}

cURL Example


curl -X POST https://www.mystoreurl.com/graphql/0.8.0/ \
  -H "Content-Type: application/json" \
  -d '{"query":"query { productGroup(id: 12345) { id title description productsCount } }"}'

JavaScript Example


async function fetchProductGroup(productGroupId) {
  const query = `
    query {
      productGroup(id: ${productGroupId}) {
        id
        title
        description
        productsCount
      }
    }
  `;
 
  try {
    const response = await fetch('https://www.mystoreurl.com/graphql/0.8.0/', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ query }),
    });
 
    const json = await response.json();
 
    if (json.errors) {
      console.error('GraphQL errors:', json.errors);
      return null;
    }
 
    return json.data.productGroup;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}
 
// Usage example
fetchProductGroup(12345).then(productGroup => {
  if (productGroup) {
    console.log('Product Group:', productGroup);
  } else {
    console.log('Failed to fetch product group.');
  }
});

Response Format

The response contains a productGroup object with the requested fields. Example response for a basic query:


{
  "data": {
    "productGroup": {
      "id": 12345,
      "title": "Summer Collection",
      "description": "<p>Explore our exclusive summer collection.</p>",
      "productsCount": 150
    }
  }
}

For advanced queries, nested objects such as productGroups, parent, breadcrumbs, filters, and products will be included as per the requested fields.

Error Handling

Error Code	Description	Handling Recommendation
`BAD_USER_INPUT`	Invalid or missing `id` argument.	Verify that the `id` argument is provided and is a valid integer.
`NOT_FOUND`	Product group with the specified ID does not exist.	Inform the user that the requested product group was not found.
`INTERNAL_ERROR`	Unexpected server error.	Retry the request after some time or contact support if persistent.
`RATE_LIMIT_EXCEEDED`	Too many requests in a short period.	Implement exponential backoff and retry later.

Errors are returned in the errors array in the GraphQL response.

Performance Considerations

Avoid requesting unnecessary fields to reduce response size and improve performance.
Use pagination when querying nested products to limit the number of products returned per request.
Cache responses where possible, especially for frequently accessed product groups.
Be mindful of rate limits; excessive requests may result in temporary blocking.
Filtering and sorting should be applied client-side or via available filters to optimize data retrieval.

Authentication

This API currently does not require authentication. However, authentication requirements may be introduced in future versions. Monitor API updates for any changes to authentication requirements.

ProductGroup: The main return type representing product groups.
Filter: Represents filters available for the product group.
ProductConnection: Connection type for paginated products within the product group.

Notes

The parent field returns false if the product group has no parent.
The filters field may be null if no filters are set for the product group.
The products field supports pagination through the edges and pageInfo fields.
Use the breadcrumbs field to build navigation paths in UI.
SEO fields (seoTitle, seoDescription, seoKeywords) help optimize search engine visibility.