Legacy Commerce API facet management deprecation

This is for:

System Administrator

The legacy Commerce API-based facet management approach for Coveo-powered search and listing pages is being deprecated in August 31, 2026. Going forward, all facet collections must be created and managed using the Facet manager in the Coveo Merchandising Hub (CMH).

All Coveo organizations using legacy Commerce API facet configurations must migrate to the Facet manager before the deprecation date. After this date, legacy facet configurations will no longer be supported, and facets managed through the deprecated approach will stop functioning on Coveo-powered search and listing pages.

Timeline

Date Milestone

January 26, 2026

Facet manager available in the Coveo Merchandising Hub (CMH) for all Coveo for Commerce organizations. Voluntary migration period begins.

August 22, 2026

Legacy Commerce API facet configurations are officially deprecated and no longer supported. facets configured through the legacy approach stop functioning.

Scope

Your Coveo organization is affected if it uses the legacy Commerce API-based facet configuration model to manage facets on Coveo-powered search and listing pages.

This deprecation applies to the legacy facet configuration exposed through the following Commerce API endpoints:

To determine whether your Coveo organization uses the legacy Commerce API facet configuration

What happens after the deprecation date?

After August 31, 2026:

  • Legacy Commerce API facet configurations will stop functioning.

  • facets configured through the legacy approach will no longer appear on Coveo-powered search result pages and listing pages. This can result in degraded search navigation and filtering experiences for your storefronts.

To avoid disruption, complete the required migration steps before the deprecation date.

Benefits of migrating

Migrating to the Facet manager in the Coveo Merchandising Hub (CMH) brings meaningful improvements to your Commerce experience:

  • Centralized, merchandiser-friendly facet management. Manage all your storefront facets from a single location in the Coveo Merchandising Hub (CMH), with an intuitive interface designed for merchandisers rather than a developer-facing API.

  • Reusable facet collections with improved governance. Create and manage reusable facet collections that maintain consistency across your storefronts, reduce configuration drift, and simplify long-term maintenance of facet behavior across search and listing pages.

  • Facet performance insights. Monitor facet engagement with the built-in Performance tab, giving merchandisers visibility into which facets visitors interact with most.

  • Continued investment. Only the Facet manager approach will receive future improvements and new capabilities. Migrating now means your Coveo organization benefits from ongoing Coveo investment in facet management.

Your existing storefronts will continue to work without modifications once migration is complete. The migration is a configuration-level change.

Required actions

Coveo organizations using legacy Commerce API facet configurations must complete the following migration steps before August 31, 2026.

Step 1: Create facet collections in the Facet manager

Using the Facet manager, create facet collections that replicate your existing legacy Commerce API facet configurations.

For each property in the Coveo Merchandising Hub (CMH):

  1. Create a default search facet collection that replicates your existing Commerce API global search facet configuration.

  2. Create a default listing facet collection that replicates your existing Commerce API global listing facet configuration.

  3. Create specific facet collections that replicate any existing Commerce API specific listing facet configurations.

Step 2: Enable the new facet management feature flag

After creating your facet collections, contact your Coveo representative to enable the new facet management feature flag on your Coveo organization. This flag controls whether the Commerce API uses the Facet manager configurations or the legacy facet configurations at query time.

The feature flag applies to the entire Coveo organization and can’t be controlled per property.

Tip
Tip

Enable the feature flag on a non-production Coveo organization first to validate the migration before enabling it in production.

Step 3: Validate facet behavior

Once the feature flag is enabled, validate that facets appear as expected on your storefront search and listing pages.

Step 4: Remove reliance on legacy configurations

After confirming that the Facet manager configurations work as expected, remove any custom scripts, automation, or implementation workflows that depend on legacy Commerce API facet configurations.

Learn more

Get help

If you have questions about the migration or need help, contact your Coveo representative.