Documentation
All Release Notes
Product Search in GraphQL now available in public beta
30 September 2025
Composable Commerce
HTTP API
New feature
GraphQLProduct catalogSearch
Product Search is now available in the GraphQL API in public beta. You can now perform powerful Product Search queries directly within our GraphQL endpoint, eliminating the need for multiple API calls and simplifying your frontend development.

Previously, the process required two distinct API calls:

  1. to the Product Search endpoint to get a list of Product IDs.
  2. to the GraphQL endpoint to fetch the specific data needed for those Products.

This two-call pattern placed the responsibility of data aggregation on the client and could introduce additional network round-trips. Our new approach removes this requirement.

Our GraphQL API now enables you to query, search, and retrieve the exact product data you need with a single API call. This minimizes the risk of over-fetching or under-fetching data and simplifies your data retrieval logic. This feature allows you to fetch product variants flexibly, including all variants or only the Master Variant, and supports filtering, sorting, and faceting.
For more details and usage examples, see the GraphQL API documentation.

Changes:

  • [GraphQL API] Changed the Query type:
    • Added the productsSearch field to the Query type.
  • [GraphQL API] Added the following types to the GraphQL schema: ProductPagedSearchResponse, ProductSearchFacetResultBucket, ProductSearchFacetResultBucketEntry, ProductSearchFacetResultCount, ProductSearchFacetResultStats, and ProductSearchResult.
  • [GraphQL API] Added the following input types to the GraphQL schema: ProductSearchFacetCountExpressionInput, ProductSearchFacetDistinctBucketSortExpressionInput, ProductSearchFacetDistinctExpressionInput, ProductSearchFacetExpressionInput, ProductSearchFacetRangesExpressionInput, ProductSearchFacetRangesFacetRangeInput, ProductSearchFacetStatsExpressionInput, SearchAnyValueExpressionInput, SearchDateRangeExpressionInput, SearchDateTimeRangeExpressionInput, SearchExistsInput, SearchFilterExpressionInput, SearchFullTextExpressionInput, SearchFullTextPrefixInput, SearchFuzzyExpressionInput, SearchLongRangeExpressionInput, SearchNumberRangeExpressionInput, SearchQueryInput, SearchQueryRangeExpressionInput, SearchSortingInput, and SearchTimeRangeExpressionInput.
  • [GraphQL API] Added the following enums to the GraphQL schema: ProductSearchFacetCountLevelEnum, ProductSearchFacetDistinctBucketSortBy, ProductSearchFacetScopeEnum, SearchFieldType, SearchMatchType, SearchSortMode, and SearchSortOrder.
  • [GraphQL API] Added the ProductSearchFacetResult interface to the GraphQL schema.
  • [GraphQL API] Added the following scalar to the GraphQL schema: SearchValueType.

The following changes were introduced in terms of GraphQL SDL:

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductPagedSearchResponse {
  total: Long!
  offset: Int
  limit: Int
  results: [ProductSearchResult!]!
  facets: [ProductSearchFacetResult!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetCountExpressionInput {
  name: String!
  scope: ProductSearchFacetScopeEnum = all
  filter: SearchQueryInput
  level: ProductSearchFacetCountLevelEnum = products
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum ProductSearchFacetCountLevelEnum {
  "ProductSearchFacetCountLevelEnum 'products' type."
  products

  "ProductSearchFacetCountLevelEnum 'variants' type."
  variants
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum ProductSearchFacetDistinctBucketSortBy {
  "ProductSearchFacetDistinctBucketSortBy 'count' type."
  count

  "ProductSearchFacetDistinctBucketSortBy 'key' type."
  key
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetDistinctBucketSortExpressionInput {
  by: ProductSearchFacetDistinctBucketSortBy!
  order: SearchSortOrder
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetDistinctExpressionInput {
  name: String!
  scope: ProductSearchFacetScopeEnum
  filter: SearchQueryInput
  level: ProductSearchFacetCountLevelEnum
  field: String!
  includes: [String!]
  sort: ProductSearchFacetDistinctBucketSortExpressionInput
  limit: Int
  language: String
  fieldType: SearchFieldType
  missing: String
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetExpressionInput {
  count: ProductSearchFacetCountExpressionInput
  distinct: ProductSearchFacetDistinctExpressionInput
  ranges: ProductSearchFacetRangesExpressionInput
  stats: ProductSearchFacetStatsExpressionInput
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetRangesExpressionInput {
  name: String!
  scope: ProductSearchFacetScopeEnum
  filter: SearchQueryInput
  level: ProductSearchFacetCountLevelEnum
  field: String!
  ranges: [ProductSearchFacetRangesFacetRangeInput!]!
  language: String
  fieldType: SearchFieldType
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetRangesFacetRangeInput {
  from: String
  to: String
  key: String
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
interface ProductSearchFacetResult {
  name: String!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSearchFacetResultBucket implements ProductSearchFacetResult {
  name: String!
  buckets: [ProductSearchFacetResultBucketEntry!]!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSearchFacetResultBucketEntry {
  key: String!
  count: Int!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSearchFacetResultCount implements ProductSearchFacetResult {
  name: String!
  value: Long!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSearchFacetResultStats implements ProductSearchFacetResult {
  name: String!
  min: Json!
  max: Json!
  mean: Json
  sum: Json
  count: Long!
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum ProductSearchFacetScopeEnum {
  "ProductSearchFacetScopeEnum 'all' type."
  all

  "ProductSearchFacetScopeEnum 'query' type."
  query
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input ProductSearchFacetStatsExpressionInput {
  name: String!
  scope: ProductSearchFacetScopeEnum
  filter: SearchQueryInput
  field: String!
  fieldType: SearchFieldType
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
type ProductSearchResult {
  id: String!
  product: Product!
}

extend type Query {
  "BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
  productsSearch(query: SearchQueryInput, postFilter: SearchQueryInput, sort: [SearchSortingInput!], limit: Int, offset: Int, markMatchingVariants: Boolean, facets: [ProductSearchFacetExpressionInput!]): ProductPagedSearchResponse
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchAnyValueExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  gte: Float
  value: SearchValueType!
  language: String
  caseInsensitive: Boolean
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchDateRangeExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  gte: Date
  gt: Date
  lte: Date
  lt: Date
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchDateTimeRangeExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  gte: DateTime
  gt: DateTime
  lte: DateTime
  lt: DateTime
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchExistsInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  language: String
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum SearchFieldType {
  "Field type for boolean values."
  boolean

  "Field type for text values."
  text

  "Field type for localized text values."
  ltext

  "Field type for enum values."
  enum

  "Field type for localized enum values."
  lenum

  "Field type for number values."
  number

  "Field type for money values."
  money

  "Field type for date values."
  date

  "Field type for datetime values."
  datetime

  "Field type for time values."
  time

  "Field type for reference values."
  reference

  "Field type for set of boolean values."
  set_boolean

  "Field type for set of text values."
  set_text

  "Field type for set of localized text values."
  set_ltext

  "Field type for set of enum values."
  set_enum

  "Field type for set of localized enum values."
  set_lenum

  "Field type for set of number values."
  set_number

  "Field type for set of money values."
  set_money

  "Field type for set of date values."
  set_date

  "Field type for set of datetime values."
  set_datetime

  "Field type for set of time values."
  set_time

  "Field type for set of reference values."
  set_reference
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchFilterExpressionInput {
  range: SearchQueryRangeExpressionInput
  fullText: SearchFullTextExpressionInput
  fullTextPrefix: SearchFullTextPrefixInput
  exists: SearchExistsInput
  prefix: SearchAnyValueExpressionInput
  wildcard: SearchAnyValueExpressionInput
  exact: SearchAnyValueExpressionInput
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchFullTextExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  value: String!
  language: String
  mustMatch: SearchMatchType
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchFullTextPrefixInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  value: String!
  language: String
  mustMatch: SearchMatchType
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchFuzzyExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  value: String!
  level: Int!
  language: String
  mustMatch: SearchMatchType
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchLongRangeExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  gte: Long
  gt: Long
  lte: Long
  lt: Long
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
enum SearchMatchType {
  "Any match type."
  any

  "All match type."
  all
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchNumberRangeExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  gte: Float
  gt: Float
  lte: Float
  lt: Float
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchQueryInput {
  and: [SearchQueryInput!]
  or: [SearchQueryInput!]
  not: [SearchQueryInput!]
  filter: [SearchFilterExpressionInput!]
  range: SearchQueryRangeExpressionInput
  fullText: SearchFullTextExpressionInput
  fullTextPrefix: SearchFullTextPrefixInput
  exists: SearchExistsInput
  prefix: SearchAnyValueExpressionInput
  wildcard: SearchAnyValueExpressionInput
  exact: SearchAnyValueExpressionInput
  fuzzy: SearchFuzzyExpressionInput
}

"BETA: This feature can be subject to change and should be used carefully in production. https://docs.commercetools.com/api/contract#public-beta"
input SearchQueryRangeExpressionInput {
  date: SearchDateRangeExpressionInput
  datetime: SearchDateTimeRangeExpressionInput
  time: SearchTimeRangeExpressionInput
  long: SearchLongRangeExpressionInput
  float: SearchNumberRangeExpressionInput
}

"BETA: This feature can be subject to change and should be used carefully in production.
https://docs.commercetools.com/api/contract#public-beta"
enum SearchSortMode {
  "Minimum value."
  min

  "Maximum value."
  max

  "Average value."
  avg

  "Sum value."
  sum
}

"BETA: This feature can be subject to change and should be used carefully in production.
https://docs.commercetools.com/api/contract#public-beta"
enum SearchSortOrder {
  "Ascending order."
  asc

  "Descending order."
  desc
}

"BETA: This feature can be subject to change and should be used carefully in production.
https://docs.commercetools.com/api/contract#public-beta"
input SearchSortingInput {
  field: String!
  language: String
  order: SearchSortOrder!
  mode: SearchSortMode
  fieldType: SearchFieldType
  filter: SearchFilterExpressionInput
}

"BETA: This feature can be subject to change and should be used carefully in production.
https://docs.commercetools.com/api/contract#public-beta"
input SearchTimeRangeExpressionInput {
  field: String!
  boost: Float
  fieldType: SearchFieldType
  gte: Time
  gt: Time
  lte: Time
  lt: Time
}

scalar SearchValueType