--- 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/) must be created and managed using the [Facet manager](https://docs.coveo.com/en/p63f0211/) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/). All [Coveo organizations](https://docs.coveo.com/en/185/) using legacy Commerce API facet configurations must migrate to the [Facet manager](https://docs.coveo.com/en/p63f0211/) before the deprecation date. After this date, legacy facet configurations will no longer be supported, and [facets](https://docs.coveo.com/en/198/) 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/) available in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) for all Coveo for Commerce [organizations](https://docs.coveo.com/en/185/). 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/) configured through the legacy approach stop functioning. |=== ## Scope Your [Coveo organization](https://docs.coveo.com/en/185/) is affected if it uses the legacy Commerce API-based facet configuration model to manage [facets](https://docs.coveo.com/en/198/) 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/) uses the legacy Commerce API facet configuration * You're using the legacy approach if your implementation configures [facets](https://docs.coveo.com/en/198/) 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/) or [legacy listing configurations](https://docs.coveo.com/en/o78c0306/) documentation. * You're not affected if you already create and manage your [facet collections](https://docs.coveo.com/en/p5890502/) exclusively through the [Facet manager](https://docs.coveo.com/en/p63f0211/) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/). If you're already using the [Facet manager](https://docs.coveo.com/en/p63f0211/) for all your Commerce [facets](https://docs.coveo.com/en/198/), 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/) 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/). 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/) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) brings meaningful improvements to your Commerce experience: * **Centralized, merchandiser-friendly facet management.** Manage all your storefront [facets](https://docs.coveo.com/en/198/) from a single location in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/), 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/) that maintain consistency across your [storefronts](https://docs.coveo.com/en/p33g0410/), 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/) with the built-in **Performance** tab, giving merchandisers visibility into which [facets](https://docs.coveo.com/en/198/) visitors interact with most. * **Continued investment.** Only the [Facet manager](https://docs.coveo.com/en/p63f0211/) approach will receive future improvements and new capabilities. Migrating now means your [Coveo organization](https://docs.coveo.com/en/185/) benefits from ongoing Coveo investment in facet management. Your existing [storefronts](https://docs.coveo.com/en/p33g0410/) 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/) 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/), create [facet collections](https://docs.coveo.com/en/p5890502/) that replicate your existing legacy Commerce API facet configurations. For each [property](https://docs.coveo.com/en/p4ue0547/) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/): . Create a default search [facet collection](https://docs.coveo.com/en/p5890502/) that replicates your existing Commerce API global search facet configuration. . Create a default listing [facet collection](https://docs.coveo.com/en/p5890502/) that replicates your existing Commerce API global listing facet configuration. . Create specific [facet collections](https://docs.coveo.com/en/p5890502/) 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/), contact your Coveo representative to enable the new facet management feature flag on your [Coveo organization](https://docs.coveo.com/en/185/). This flag controls whether the Commerce API uses the [Facet manager](https://docs.coveo.com/en/p63f0211/) configurations or the legacy facet configurations at query time. The feature flag applies to the entire [Coveo organization](https://docs.coveo.com/en/185/) and can't be controlled per [property](https://docs.coveo.com/en/p4ue0547/). > **Tip** > > Enable the feature flag on a non-production [Coveo organization](https://docs.coveo.com/en/185/) 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/) 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/) 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/) * [Facets for search](https://docs.coveo.com/en/p4ug0578/) * [Facets for product listing pages](https://docs.coveo.com/en/p5da0252/) * [Create search configurations (legacy)](https://docs.coveo.com/en/o7mc0039/) * [Create listing configurations (legacy)](https://docs.coveo.com/en/o78c0306/) ## Get help If you have questions about the migration or need help, contact your Coveo representative.