Standalone module

Product catalog

Learn how the new Product Attributes and Product Search capabilities fundamentally improve the management and discoverability of your Product data.

Ask about this Page

Copy for LLM

View as Markdown

After completing this page, you should be able to:

Describe the purpose and benefits of the new Product Attributes feature.
Explain how attribute filtering in the Product Projections API improves performance.
Demonstrate the use of fuzzy search, statistical facets, and discounted price filters in the Product Search API.
Identify the benefits of using the onlyMatching parameter set to true in GraphQL Product Projection Search.
Summarize the functionality and benefits of the Smart Data Modeler.

Product Projections

In modern commerce, every millisecond counts, and sometimes, the data you don't load is just as important as the data you do.

Before the introduction of attribute filtering, when you fetched a Product Projection, the response included all associated attributes for the Master Variant and all other Variants. While comprehensive, this often led to overfetching and unnecessarily large payload sizes, especially for complex products with hundreds of attributes.

We're excited to introduce the new filter[attributes] query parameter. This allows you to surgically specify exactly which Product Attributes (on the Product, Master Variant, or other Variants) you want to be included in (or excluded from) the API response.

The new filter[attributes] parameter is available across all core Product Projection endpoints, including queries, fetching by ID, fetching by key, and store-scoped requests.

Using it is straightforward, supporting both inclusion (whitelist) and exclusion (blacklist) modes:

Including specific Attributes (Whitelist)

To request only a specific set of attributes, simply provide a list of the attribute names. Any attribute not listed will be omitted from the response.

Syntax: filter[attributes]=attributeName1,attributeName2

For example, let's try to get a current Product Projection of a specific product (Rustic Country Queen Bed), but we only want to see the information about the color and finish for each variant:

Requestbash

curl --get \
"https://api.{region}.commercetools.com/{projectKey}/product-projections/key=rustic-country-queen-bed?filter[attributes]=search-color&filter[attributes]=search-finish" \
--header "Authorization: Bearer {bearerToken}" \
| jq

Resultjson

{
  "id": "70ab1f54-277e-4504-87f3-cdae3d5be73d",
  "version": 3,
  "productType": {
    "typeId": "product-type",
    "id": "415bec3b-e1de-4bbd-8c62-e537937ec817"
  },
  "name": {
    "en-US": "Rustic Country Queen Bed",
    "en-GB": "Rustic Country Queen Bed",
    "de-DE": "Rustikales Queensize-Bett im Landhausstil"
  },
...
    "attributes": [
      {
        "name": "search-finish",
        "value": {
          "key": "brown",
          "label": {
            "en-US": "Brown",
            "en-GB": "Brown",
            "de-DE": "Braun"
          }
        }
      },
      {
        "name": "search-color",
        "value": {
          "key": "yellow",
          "label": {
            "en-US": "Yellow",
            "en-GB": "Yellow",
            "de-DE": "Gelb"
          }
        }
      }
    ],
...
}

Excluding Specific Attributes (Blacklist)

To fetch all attributes except a few, use the minus sign (-) prefix before the attribute name.

Syntax: filter[attributes]=-attributeName1

If we want to get all attributes except search-color:

Requestbash

curl --get \
"https://api.{region}.commercetools.com/{projectKey}/product-projections/key=rustic-country-queen-bed?filter%5Battributes%5D=-search-color" \
--header "Authorization: Bearer {bearerToken}" \
| jq

Resultjson

{
...
    "attributes": [
      {
        "name": "search-finish",
        "value": {
          "key": "brown",
          "label": {
            "en-US": "Brown",
            "en-GB": "Brown",
            "de-DE": "Braun"
          }
        }
      },
      {
        "name": "finish-code",
        "value": "#8b4513"
      },
      {
        "name": "productspec",
        "value": {
          "en-US": "- Leather upholstery\n- Standard Queen size\n- Assembly on site",
          "en-GB": "- Leather upholstery\n- Standard Queen size\n- Assembly on site",
          "de-DE": "- Leather upholstery\n- Standard Queen size\n- Assembly on site"
        }
      },
      {
        "name": "finish-label",
        "value": {
          "en-GB": "Saddle Brown",
          "de-DE": "Sattel braun",
          "en-US": "Saddle Brown"
        }
      },
      {
        "name": "color-label",
        "value": {
          "en-GB": "Tan",
          "de-DE": "Bräunen",
          "en-US": "Tan"
        }
      },
      {
        "name": "color-code",
        "value": "#D2B48C"
      }
    ],
...
}

This new Attribute Filtering functionality is a prime example of how commercetools is continuously focused on developer experience and performance. By reducing unnecessary data payloads, you gain immediate, measurable improvements in application speed and efficiency. Make sure to integrate the filter[attributes] parameter into your next project or optimization sprint to unlock these benefits!

Product Search

A strategic advantage in e-commerce, effective product search goes beyond a mere technical function. It directly impacts customer satisfaction, drives conversion rates, and is crucial for overall success. This is precisely why the Product Search API was introduced in 2024 and continuously improved throughout 2025. Let's have a look at some of the new features that have been introduced over the course of last year.

Product Search relies on an index of your Product data to return fast and relevant results, so indexing must be enabled for your Project before you can use it. Before diving in, you'll need to check if Product Search is activated for your Project. This can be done by a simple API request to get your Project information, or by opening your Project in the Merchant Center, going to Settings → Project Settings → Storefront Search, and making sure that Product Search indexing is set to active.

The Product Search API's speed comes from its ID-first design; it traditionally returned only the IDs of matching Products, requiring a second step to fetch product details via GraphQL.

Now, with Product Search functionality integrated directly into the GraphQL API, you can query and retrieve product details in a single streamlined step.

Now all we need is a tool that would help us create, validate, and test our GraphQL Product Search queries.

Fortunately, you don't have to wish for a tool like that—we already have one! Simply open the Merchant Center and navigate to Settings → Developer Settings → GraphQL Explorer.

How about we use it to test out some new features that were introduced to Product Search in 2025?

Fuzzy search

Searching for desired products is a crucial functionality that is not only desired, but expected from commerce platforms. We can all agree however how annoying it can be when we can't recall the exact name of the product or when typos creep in, preventing customers from finding exactly what they were looking for. Fortunately, Product Search now supports fuzzy search queries. Not only that, you can adjust the "fuzziness level" to determine how tolerant the query can be. While allowed fuzziness values are 0, 1, and 2, the API dynamically adjusts the effective level based on the length of each search term: 0 for 1–2 characters (exact match), 1 for 3–5 characters (up to one difference), and 2 for terms over 5 characters (up to two differences).

Without the fuzzy query, a standard fullText search for a misspelling like "tarditional" would typically fail to find any relevant products. However, the introduction of the new fuzzy query increases the likelihood of successfully finding these products despite the typo:

Requestgraphql

query FuzzySearch {
  productsSearch(
    query: {fuzzy: {field: "name", value: "tarditional", level: 2, language: "en-GB"}}
  ) {
    results {
      product {
        key
      }
    }
  }
}

Resultjson

{
  "data": {
    "productsSearch": {
      "results": [
        {
          "product": {
            "key": "traditional-armchair"
          }
        },
        {
          "product": {
            "key": "traditional-l-seater-sofa"
          }
        },
        {
          "product": {
            "key": "traditional-three-seater-sofa"
          }
        }
      ]
    }
  }
}

Statistical facets

But what if we would like to get some statistical information about some numeric properties of our products? For example about their EUR price for German customers? This is now possible thanks to a new addition to the Product Search API, statistical facets—a new type of facet that provides statistical aggregations (min, max, average, sum, count) for number and date fields in search results. This offers insights into product data without client-side calculation using multiple queries.

Let's use it to expand our previous request:

Requestgraphql

query FuzzySearchWithGermanPriceStats {
  productsSearch(
    query: {fuzzy: {field: "name", value: "tarditional", level: 2, language: "en-GB"}}
    facets: {stats: {name: "priceStatistics", field: "variants.prices.centAmount", filter: {and:[{exact: {field: "variants.prices.currencyCode", value: "EUR"}}, {exact: {field: "variants.prices.country", value: "DE"}}]}}}
  ) {
    results {
      product {
        key
        masterData {
          current {
            allVariants {
              prices {
                country
                value {
                  centAmount
                  currencyCode
                }
              }
            }
          }
        }
      }
    }
    facets {
      ... on ProductSearchFacetResultStats {
        name
        count
        sum
        min
        max
        mean
      }
    }
  }
}

Resultjson

{
  "data": {
    "productsSearch": {
      "results": [
        ...
      ],
      "facets": [
        {
          "name": "priceStatistics",
          "count": 3,
          "sum": 629700,
          "min": 29900,
          "max": 359900,
          "mean": 209900
        }
      ]
    }
  }
}

We now have not only the count of prices that meet our requirements but also valuable statistical information about them.

Filter by discounted prices

What if you only want to retrieve discounted "traditional" products? This is now achievable thanks to the newly introduced feature that allows you to query Products based on whether any of their Product Variants are currently discounted.

Requestgraphql

query FuzzySearchForDiscountedProducts {
  productsSearch(
    query: {and: [{fuzzy: {field: "name", language: "en-GB", level: 2, value: "tarditional"}}, {exact: {field: "variants.prices.discounted", value: true}}]}
  ) {
    offset
    limit
    results {
      id
      product {
        key
        masterData {
          current {
            allVariants {
              prices {
                discounted {
                  value {
                    centAmount
                    currencyCode
                  }
                }
                value {
                  centAmount
                  currencyCode
                }
              }
            }
          }
        }
      }
    }
  }
}

Resultjson

{
  "data": {
    "productsSearch": {
      "offset": 0,
      "limit": 10,
      "results": [
        {
          "id": "58084c1e-ccde-4c6d-9fd7-afc2ecd05673",
          "product": {
            "key": "traditional-armchair",
            "masterData": {
              "current": {
                "allVariants": [
                  {
                    "prices": [
                      {
                        "discounted": {
                          "value": {
                            "centAmount": 25415,
                            "currencyCode": "EUR"
                          }
                        },
                        "value": {
                          "centAmount": 29900,
                          "currencyCode": "EUR"
                        }
                      },
                      {
                        "discounted": {
                          "value": {
                            "centAmount": 25415,
                            "currencyCode": "GBP"
                          }
                        },
                        "value": {
                          "centAmount": 29900,
                          "currencyCode": "GBP"
                        }
                      },
                      {
                        "discounted": {
                          "value": {
                            "centAmount": 25415,
                            "currencyCode": "USD"
                          }
                        },
                        "value": {
                          "centAmount": 29900,
                          "currencyCode": "USD"
                        }
                      }
                    ]
                  }
                ]
              }
            }
          }
        }
      ]
    }
  }
}

Search for Product Variants in Stores

A significant enhancement to Product Search is the new capability to locate Product Variants that are available in specific Stores, regardless of how many active selections that Store has, or within specific Store Selections. Previously, this was only feasible if the entire Product belonged to the selection. Let's give it a try:

Requestgraphql

query FindVariantsBelongingToStore {
  productsSearch(
    query: {exact: {value: "a748b5f7-54b3-48f4-b744-fafb4b5d9f2c", field: "variants.stores"}}
    markMatchingVariants: true
  ) {
    results {
      product {
        key
        masterData {
          current {
            allVariants(onlyMatching: true) {
              sku
            }
          }
        }
      }
    }
  }
}

Resultjson

{
  "data": {
    "productsSearch": {
      "results": [
        {
          "product": {
            "key": "modern-three-seater-sofa",
            "masterData": {
              "current": {
                "allVariants": [
                  {
                    "sku": "MTSS-01"
                  }
                ]
              }
            }
          }
        },
        {
          "product": {
            "key": "maya-pillow-cover",
            "masterData": {
              "current": {
                "allVariants": [
                  {
                    "sku": "MPC-02"
                  }
                ]
              }
            }
          }
        }
      ]
    }
  }
}

The significant enhancements to Product Search in 2025—including fuzzy search, statistical facets, discounted price filters, and granular variant selection—collectively deliver a powerful, flexible, and high-performance search experience. By leveraging these new capabilities, Functional Architects can design storefronts that are more resilient to user error, provide deeper analytical insights on pricing, and offer precise control over store-specific product visibility, ultimately leading to improved conversion rates and a superior customer experience.

Product Projection Search

Since we're on the topic of GraphQL and searching, when you perform a product search (via the productProjectionSearch query in GraphQL), your search criteria might target specific attributes of a variant (for example, "red shirt, size medium"). While the search results correctly return the parent product, the variants and allVariants fields on that product traditionally returned all variants of that product.

This meant that if your search was successful, you still had to implement client-side filtering to isolate the one or two variants that actually matched your original search query. This adds unnecessary complexity and overhead to your application.

Thankfully that is in the past, because in 2025, we've introduced the onlyMatching: Boolean argument to the variants and allVariants fields within the ProductProjection type.

When you set onlyMatching: true, the commercetools API takes on the responsibility of filtering the list of variants, ensuring that the response only includes the Product Variants that matched your original productProjectionSearch query.

To illustrate the elegance and efficiency of this new feature, let's look at a GraphQL query example.

Let's take a product like "Nala Two-Seater Sofa" with seven variants (various colors and finishes). You search for a sofa that is blue:

Requestgraphql

query FindBlueSofa {
  productProjectionSearch(
    text: "sofa"
    locale: "en-US"
    filters: {model: {value: {path: "variants.attributes.search-color.key", values: "blue"}}}
    markMatchingVariants: true
  ) {
    results {
      key
      allVariants(onlyMatching: true) {
        sku
      }
    }
  }
}

Resultjson

{
  "data": {
    "productProjectionSearch": {
      "results": [
        {
          "key": "nala-two-seater-sofa",
          "allVariants": [
            {
              "sku": "NTSS-02"
            },
            {
              "sku": "NTTS-04"
            }
          ]
        }
      ]
    }
  }
}

As you can see in the result, even though this product has seven variants, our search only returned the two which meet the search criteria.

Product catalog

Learn how the new Product Attributes and Product Search capabilities fundamentally improve the management and discoverability of your Product data.

Product Projections.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Including specific Attributes (Whitelist).css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Excluding Specific Attributes (Blacklist).css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product Search.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Fuzzy search.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Statistical facets.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Filter by discounted prices.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Search for Product Variants in Stores.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product Projection Search.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Test your knowledge.css-c0cbbx{display:inline-block;}.css-c0cbbx >:disabled{pointer-events:none;}

Product Projections

Including specific Attributes (Whitelist)

Excluding Specific Attributes (Blacklist)

Product Search

Fuzzy search

Statistical facets

Filter by discounted prices

Search for Product Variants in Stores

Product Projection Search

Test your knowledge