Migrate to Product Search

The migration consists of the following steps:

1. Inventory your current usage
2. Activate the Product Search API
3. Migrate the query
4. Migrate full-text search
5. Migrate fuzzy search
6. Migrate filters
7. Migrate facets
8. Migrate sorting
9. Migrate pagination
10. Retrieve full Product data
11. Verify and roll out
12. Decommission Product Projection Search

Key differences

Five of these changes require design decisions rather than a mechanical rewrite. Read them before you start.

• The response contains IDs, not Products. You need a second step to retrieve the data you render. See Retrieve full Product data.
• Full-text search is explicit per field. The text.{language} parameter searched a fixed set of fields with name weighted heavier. You now compose the fields and their weights yourself. See Migrate full-text search.
• Only the current Product representation is indexed. No equivalent of staged=true exists. For staged data, use the Query ProductProjections endpoint with staged=true.
• Price selection happens after the search. Use the variants.prices.* fields to filter and sort, and apply price selection during data retrieval.
• Product Search has no GET method. All requests go to Search Products. If you cache Product Listing Page responses on a CDN keyed by URL, that strategy needs to change.

Inventory your current usage

List every Product Projection Search call in your integration and record the following for each. This list is both your migration checklist and your test matrix.

• The query parameters used: text.{locale}, fuzzy, fuzzyLevel, filter.query, filter, filter.facets, facet, sort, expand, staged, markMatchingVariants, the price selection parameters, localeProjection, and storeProjection.
• The fields your storefront reads from each response.
• Whether the caller needs staged data.
• Whether the caller relies on facet counts being Product Variant counts. This default changes; see Set the facet counting level.

Activate the Product Search API

Product Search is not active by default, and activating it triggers indexing. Activate it early so the index is ready before you start testing.

curl -sH "Authorization: Bearer {access_token}" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "version": {version_number},
    "actions": [
      {
        "action": "changeProductSearchIndexingEnabled",
        "enabled": true,
        "mode": "ProductsSearch"
      }
    ]
  }' https://api.{region}.commercetools.com/{projectKey}

Migrate the query

Move each Product Projection Search parameter to its Product Search equivalent.

Migrate full-text search

This step has the largest effect on which results your storefront returns, so treat it as a redesign rather than a translation.

GET /{projectKey}/product-projections/search?text.en=red+shoes

{
  "query": {
    "or": [
      { "fullText": { "field": "name", "language": "en", "value": "red shoes", "boost": 3 } },
      { "fullText": { "field": "searchKeywords", "language": "en", "value": "red shoes", "boost": 2 } },
      { "fullText": { "field": "description", "language": "en", "value": "red shoes" } },
      { "fullText": { "field": "slug", "language": "en", "value": "red shoes" } },
      { "exact": { "field": "variants.sku", "value": "red shoes" } }
    ]
  }
}

Note the following differences in behavior:

• fullText requires all provided terms to match by default. Set mustMatch to any to match any term, which is closer to the behavior of a broad storefront search box.
• boost values above 1 raise relevance, values between 0 and 1 lower it.
• variants.sku is a keyword field, so it supports exact, prefix, wildcard, and fuzzy expressions, but not fullText.
• Product Search only analyzes Locales configured in the Project's languages. A query for an unconfigured Locale returns no results.
• A prefix expression on name is usually the better choice for type-ahead than a wildcard expression, which performs less efficiently.

Migrate fuzzy search

GET /{projectKey}/product-projections/search?text.en=shoes&fuzzy=true&fuzzyLevel=1

{
  "query": {
    "or": [
      { "fullText": { "field": "name", "language": "en", "value": "shoes", "boost": 3 } },
      { "fuzzy": { "field": "name", "language": "en", "value": "shoes", "level": 1 } }
    ]
  }
}

• 0 for terms of 1-2 characters.
• 1 for terms of 3-5 characters.
• 2 for longer terms.

Migrate filters

Migrate facets

Migrate sorting

Sort strings become objects, and the sort mode moves out of the sort direction.

{
  "sort": [
    { "field": "name", "language": "en", "order": "asc" },
    { "field": "id", "order": "asc" }
  ]
}

Migrate pagination

• The maximum limit drops from 500 to 100. If you request pages of more than 100 results, reduce the page size or fetch several pages.
• The maximum usable offset depends on the limit, because the 10 000-result ceiling still applies. With a limit of 100 the maximum offset is 9 900; with the default limit of 20 it is 9 980.
• Exceeding the ceiling returns an InvalidInput error instead of a SearchExecutionFailure error. Update any error handling that matches on the old error code.

Retrieve full Product data

Product Search returns Product IDs. Choose one of the following approaches to retrieve the data you render. This is also where price selection, locale projection, and Store projection now happen.

New capabilities

Product Search offers capabilities that Product Projection Search does not. Consider whether they let you simplify your implementation, or remove workarounds you built for their absence.

• Prefix matching: match the beginning of a field value with prefix expressions.
• Wildcard matching: match patterns within field values with wildcard expressions.
• Field-level boosting: control relevance scoring per field with boosting.
• Product-level Attributes: search by Attributes defined at the Product level with the attributes.{name} field, not only at the Variant level. You can remove SameForAll workarounds built for Product Projection Search.
• Standalone Prices: filter, sort, and facet on Standalone Prices.
• Stores and Product Selections: filter on the stores and productSelections fields.
• Stats facets: calculate minimum, maximum, mean, sum, and count for number and date fields with stats facets.

Indexing limits and validation

• Up to 50 Variant Attributes.
• Up to 50 Product Attributes.

The following soft limits also apply to the search index:

• 15 000 Stores per Product.
• 15 000 Product Selections per Product.
• 10 000 Standalone Prices per Product.

Exceeding a soft limit produces non-deterministic results for expressions on the affected fields.

Verify and roll out

Migrate one entry point at a time. Product Listing Pages, search result pages, Category pages, and internal tools have different requirements. Running both APIs in parallel lets you compare them safely.

1. Run both APIs in shadow mode. For a sample of live traffic, issue the old and the new request and log both result sets. Do not change what customers see yet.
2. Compare result sets, not just counts. Check total, the ID sets, their order, and the facet counts. Account for the indexing delay. Both indexes are eventually consistent and update independently. Small differences in the minutes after a catalog change are expected, so compare against a stable catalog.
3. Expect deliberate differences. Price filters now consider all Prices. Facet counts changed from Variants to Products. Relevance ranking depends on your new full-text composition. Confirm that each difference is one you intended.
4. Tune relevance. Adjust boost values, mustMatch, and the set of searched fields against real queries from your search logs before you switch traffic.
5. Roll out behind a feature toggle. Route a small share of traffic to Product Search, monitor response times and conversion, then increase the share. For the broader pattern, see Migrate checkout.
6. Keep the fallback alive. Keep the Product Projection Search path working until Product Search carries all traffic. Keep calling it as well, so its index is not deactivated automatically.

Decommission Product Projection Search

Once all traffic uses Product Search and you have validated the results:

1. Remove the Product Projection Search calls from your integration, including any fallback path.
2. Remove client code that reads isMatchingVariant, keyed facet objects, or the dataType, total, and other facet result fields.
3. Review isSearchable on your AttributeDefinitions. Attributes that remained searchable only for Product Projection Search can be set to false, which also frees capacity within the Attribute indexing limits.
4. Deactivate Product Projection Search, either in the Merchant Center or with the Change Product Search Indexing Enabled update action.

curl -sH "Authorization: Bearer {access_token}" -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "version": {version_number},
    "actions": [
      {
        "action": "changeProductSearchIndexingEnabled",
        "enabled": false,
        "mode": "ProductProjectionsSearch"
      }
    ]
  }' https://api.{region}.commercetools.com/{projectKey}

Troubleshooting

Related resources

• Storefront search overview: feature-by-feature comparison of both APIs.
• Search query language: syntax reference for expressions, sorting, and pagination.
• Product Search: API reference, searchable fields, and indexing behavior.
• Performance tips: how to keep search response times low.