Hydrogen Storefront - Product Filtering

Technical Q&A

Topic summary

A developer encountered issues filtering products by metafield values in a Hydrogen headless storefront. Their GraphQL query targeting a specific metafield (custom.flag_name) wasn’t returning the expected filtered results.

Solution identified:

  • Install the Shopify Search & Discovery app (required)
  • Enable filters for specific metafields within the app’s filter settings
  • Verify the storefront has the unauthenticated_read_product_listings access scope

Key limitation:
Metafield filtering works for collection queries but not for predictive search routes, which only support a predefined set of searchable properties documented in Shopify’s Ajax API reference.

The discussion includes a screenshot showing the Search & Discovery app configuration interface and links to relevant Shopify documentation for product filtering requirements.

Summarized with AI on October 28. AI used: claude-sonnet-4-5-20250929.
1

We are currently working on filtering products based on a metafield in a headless storefront (Hydrogen framework). We followed the documentation to create a basic query for this, but the response doesn’t include the expected metafield value for the products. Here’s the query we used:

query tumbleDryProducts {
  collection(handle: "xxxxxxxxxxx") {
    id
    handle
    title
    products(first: 10, filters: { productMetafield: { namespace: "custom", key: "flag_name", value: "top" } }) {
      nodes {
        id
        title
        metafields(identifiers: [{namespace: "custom", key: "flag_name"}]) {
          key
          value
        }
      }
    }
  }
}

We need products with specific metafield values assigned to them, but the query does not return those filtered products as expected.
Could anyone please provide guidance or fixes for this issue? We’re using the headless storefront built with Hydrogen, and any insights into the correct approach for implementing product filtering based on metafields would be greatly appreciated.

2

Hi, have you manage to find solution, or still need help ?
iam more intrigued to enable filter including metafields on search route :confused:

3

If somebody is still trying to find a solution, thing that was a blocker for me was a Shopify Search & Discovery app. You HAVE to install it and then go in that app, filters settings and enable filters for specific metafields! Check docs on this link and make sure to check first section requirements.

Screenshot 2025-05-29 at 23.06.22.png
Screenshot 2025-05-29 at 23.06.22.png3020×1396 186 KB

Regarding unauthenticated_read_product_listings access scope, my Hydorgen storefront already had this permission, but for other storefronts you might have to enable it.

1 Like
4

Does the filter work on search route tho ?

5

I haven’t explored predictive search much yet, but as far as I can tell from the documentation, it uses a predefined list of properties for searching. So, adding any filters in the Shopify Search & Discovery app only allows filtering by that field in the collections GraphQL query, as shown in the first blog post. You can see all the properties used for filtering in predictive search in the documentation here. Hope this helps!