--- title: Legacy Commerce API facet management deprecation slug: q3cc0299 canonical_url: https://docs.coveo.com/en/q3cc0299/ collection: deprecations source_format: adoc --- # Legacy Commerce API facet management deprecation 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](https://docs.coveo.com/en/p5890502.md) must be created and managed using the [Facet manager](https://docs.coveo.com/en/p63f0211.md) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md). All [Coveo organizations](https://docs.coveo.com/en/185.md) using legacy Commerce API facet configurations must migrate to the [Facet manager](https://docs.coveo.com/en/p63f0211.md) before the deprecation date. After this date, legacy facet configurations will no longer be supported, and [facets](https://docs.coveo.com/en/198.md) managed through the deprecated approach will stop functioning on Coveo-powered search and listing pages. ## Timeline [%header,cols="~,~"] |=== |Date |Milestone |January 26, 2026 |[Facet manager](https://docs.coveo.com/en/p63f0211.md) available in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md) for all Coveo for Commerce [organizations](https://docs.coveo.com/en/185.md). Voluntary migration period begins. |August 22, 2026 |Legacy Commerce API facet configurations are officially deprecated and no longer supported. [facets](https://docs.coveo.com/en/198.md) configured through the legacy approach stop functioning. |=== ## Scope Your [Coveo organization](https://docs.coveo.com/en/185.md) is affected if it uses the legacy Commerce API-based facet configuration model to manage [facets](https://docs.coveo.com/en/198.md) on Coveo-powered search and listing pages. This deprecation applies to the legacy facet configuration exposed through the following Commerce API endpoints: * [Search configurations](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Search-Configurations) * [Listing configurations](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Listing-Configurations) To determine whether your [Coveo organization](https://docs.coveo.com/en/185.md) uses the legacy Commerce API facet configuration * You're using the legacy approach if your implementation configures [facets](https://docs.coveo.com/en/198.md) by setting the `queryConfiguration.facets` property in Commerce API search or listing configuration JSON payloads, as described in the [legacy search configurations](https://docs.coveo.com/en/o7mc0039.md) or [legacy listing configurations](https://docs.coveo.com/en/o78c0306.md) documentation. * You're not affected if you already create and manage your [facet collections](https://docs.coveo.com/en/p5890502.md) exclusively through the [Facet manager](https://docs.coveo.com/en/p63f0211.md) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md). If you're already using the [Facet manager](https://docs.coveo.com/en/p63f0211.md) for all your Commerce [facets](https://docs.coveo.com/en/198.md), no action is required. ## What happens after the deprecation date? After August 31, 2026: * Legacy Commerce API facet configurations will stop functioning. * [facets](https://docs.coveo.com/en/198.md) 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](https://docs.coveo.com/en/p33g0410.md). To avoid disruption, complete the [required migration steps](#required-actions) before the deprecation date. ## Benefits of migrating Migrating to the [Facet manager](https://docs.coveo.com/en/p63f0211.md) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md) brings meaningful improvements to your Commerce experience: * **Centralized, merchandiser-friendly facet management.** Manage all your storefront [facets](https://docs.coveo.com/en/198.md) from a single location in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md), 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](https://docs.coveo.com/en/p5890502.md) that maintain consistency across your [storefronts](https://docs.coveo.com/en/p33g0410.md), reduce configuration drift, and simplify long-term maintenance of facet behavior across search and listing pages. * **Facet performance insights.** Monitor [facet engagement](https://docs.coveo.com/en/q1sa0327.md) with the built-in **Performance** tab, giving merchandisers visibility into which [facets](https://docs.coveo.com/en/198.md) visitors interact with most. * **Continued investment.** Only the [Facet manager](https://docs.coveo.com/en/p63f0211.md) approach will receive future improvements and new capabilities. Migrating now means your [Coveo organization](https://docs.coveo.com/en/185.md) benefits from ongoing Coveo investment in facet management. Your existing [storefronts](https://docs.coveo.com/en/p33g0410.md) will continue to work without modifications once migration is complete. The migration is a configuration-level change. ## Required actions [Coveo organizations](https://docs.coveo.com/en/185.md) 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](https://docs.coveo.com/en/p3oa0420.md), create [facet collections](https://docs.coveo.com/en/p5890502.md) that replicate your existing legacy Commerce API facet configurations. For each [property](https://docs.coveo.com/en/p4ue0547.md) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573.md): . Create a default search [facet collection](https://docs.coveo.com/en/p5890502.md) that replicates your existing Commerce API global search facet configuration. . Create a default listing [facet collection](https://docs.coveo.com/en/p5890502.md) that replicates your existing Commerce API global listing facet configuration. . Create specific [facet collections](https://docs.coveo.com/en/p5890502.md) that replicate any existing Commerce API specific listing facet configurations. ### Step 2: Enable the new facet management feature flag After creating your [facet collections](https://docs.coveo.com/en/p5890502.md), contact your Coveo representative to enable the new facet management feature flag on your [Coveo organization](https://docs.coveo.com/en/185.md). This flag controls whether the Commerce API uses the [Facet manager](https://docs.coveo.com/en/p63f0211.md) configurations or the legacy facet configurations at query time. The feature flag applies to the entire [Coveo organization](https://docs.coveo.com/en/185.md) and can't be controlled per [property](https://docs.coveo.com/en/p4ue0547.md). > **Tip** > > Enable the feature flag on a non-production [Coveo organization](https://docs.coveo.com/en/185.md) first to validate the migration before enabling it in production. ### Step 3: Validate facet behavior Once the feature flag is enabled, validate that [facets](https://docs.coveo.com/en/198.md) appear as expected on your storefront search and listing pages. ### Step 4: Remove reliance on legacy configurations After confirming that the [Facet manager](https://docs.coveo.com/en/p63f0211.md) configurations work as expected, remove any custom scripts, automation, or implementation workflows that depend on legacy Commerce API facet configurations. ## Learn more * [Facet manager](https://docs.coveo.com/en/p3oa0420.md) * [Facets for search](https://docs.coveo.com/en/p4ug0578.md) * [Facets for product listing pages](https://docs.coveo.com/en/p5da0252.md) * [Create search configurations (legacy)](https://docs.coveo.com/en/o7mc0039.md) * [Create listing configurations (legacy)](https://docs.coveo.com/en/o78c0306.md) ## Get help If you have questions about the migration or need help, contact your Coveo representative.