Search and listing configuration APIs deprecation

This is for:

System Administrator

The legacy search and listing configuration APIs for creating and managing product listing pages (PLPs) and query configurations are being deprecated. Going forward, PLPs must be created using the Coveo Merchandising Hub (CMH) or the Public Listing Page API, and query configurations for both search and listing pages must be managed through the Query Configurations API.

All Coveo organizations using the legacy search or listing configuration APIs must migrate to the replacement APIs before the deprecation date. After this date, the legacy API endpoints will no longer be supported.

Timeline

Date Milestone

October 1, 2025

New implementations use the Public Listing Page API and Query Configurations API by default.

November 25, 2025

Customer announcement. Existing rules and configurations are automatically migrated at the database level.

August 31, 2026

Legacy search and listing configuration API endpoints are officially deprecated and no longer supported.

Scope

Your Coveo organization is affected if it uses the legacy search or listing configuration APIs to create or manage PLPs or query configurations.

This deprecation applies to the following Commerce API endpoints:

To determine whether your Coveo organization is affected

What happens after the deprecation date?

After August 31, 2026:

  • The legacy search and listing configuration API endpoints will no longer be supported.

  • Any automation, scripts, or workflows that depend on the deprecated endpoints will stop functioning.

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

Benefits of migrating

Migrating to the Public Listing Page API and the Query Configurations API brings meaningful improvements to your Commerce experience:

  • Merchandiser-friendly listing page creation. Create and manage PLPs directly in the Coveo Merchandising Hub (CMH) with an intuitive interface, without requiring developer involvement or API calls.

  • Bulk listing page creation. Create multiple PLPs in a single API call using the Create multiple listing pages endpoint, reducing the number of API calls needed for large catalog structures.

  • Access to new CMH features. Only organizations using the new APIs can access the latest Coveo Merchandising Hub (CMH) capabilities.

  • Continued investment. Only the replacement APIs will receive future improvements and new capabilities. Migrating now means your Coveo organization benefits from ongoing Coveo investment.

Required actions

Coveo organizations using the legacy search or listing configuration APIs must complete the following migration steps before August 31, 2026.

Step 1: Update product listing page integrations

Your existing PLPs are automatically migrated at the database level. Update any automation, scripts, or workflows that create or manage PLPs to use the Public Listing Page API or the Coveo Merchandising Hub (CMH) instead of the legacy endpoints.

The new API separates page definition from merchandising rules and query configuration:

  • Page-defining rules: In the legacy API, page-defining filter rules were embedded as filterRules with "essential": true. In the new API, use the dedicated pageRules array to define a filter rule that determines which products appear on the page.

  • Merchandising rules are managed separately. The legacy API bundled ranking, pinning, and other merchandising rules directly in the listing configuration. With the new API, merchandising rules are managed through the Coveo Merchandising Hub (CMH) or dedicated endpoints, not as part of the page definition.

  • Exclude rules are no longer page-defining rules. In the legacy API, Exclude filter rules were allowed to define which products should not appear on a page. With the new API, Exclude filter rules can’t be used as page-defining rules. If you were using Exclude filter rules as page-defining rules, review your existing configurations to determine how exclude rules should be handled.

  • Query configuration is managed separately. The legacy API allowed setting pagination, sorts, and facets as part of the listing configuration through queryConfiguration. With the new API, these settings are managed through the Query Configurations API (see step 2).

Step 2: Update query configuration integrations

Your existing query configurations are automatically migrated at the database level. Update any automation, scripts, or workflows that manage pagination, sorts, or product metadata to use the Query Configurations API instead of the queryConfiguration property in the legacy endpoints.

  • For listing configurations, use the Query Configurations API with solutionType set to listing.

  • For search configurations, use the Query Configurations API with solutionType set to search.

The legacy global endpoints remain backward compatible temporarily to facilitate migration, but you must migrate before the deprecation date.

Step 3: Validate and remove legacy integrations

After confirming that your PLPs work as expected with the new APIs:

  1. Validate that PLPs appear correctly and that query configurations are applied as expected.

  2. Remove any custom scripts, automation, or workflows that depend on the legacy API endpoints.

Notes

Learn more

Get help

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