Migrating from search engine to commerce engine

With the Search API, you make a POST request to the Search API endpoint:

Depending on the parameters specified in the request body, the API processes either a search request or a recommendation request.

In Headless, this distinction implemented by using the search engine for search requests, such as performing queries and generating query suggestions, and using the recommendation engine for recommendation requests.

With the Commerce API, each product discovery solution has its own dedicated route:

In Headless, the Commerce API is integrated by initializing a single commerce engine instance and then creating dedicated sub-controllers to target the desired product discovery endpoint.

The Search API is prescriptive, meaning the front-end specifies the exact parameters of the search request, such as facets, filters, and ranking rules. As a result, the search engine is also prescriptive, requiring you to explicitly define what you want to retrieve.

In contrast, the Commerce API is declarative. The front-end describes the desired outcome, and the commerce engine determines the best way to fulfill the request based on configurations set by merchandisers in the Coveo Merchandising Hub. This approach reduces front-end complexity and gives merchandisers greater control over business logic.

For more information, see How the Commerce API interacts with the CMH.

Previously, implementations using the Search API and search engine targeted the appropriate query pipeline by creating specific query pipeline conditions based on the incoming search hub value. The front-end either explicitly specified the search hub by initializing the search engine with the value or relied on the search hub enforced by the API key or search token used to make requests to Coveo.

To target a specific catalog entity, implementations added a query pipeline filter to the pipeline.

New implementations using the Commerce API and commerce engine have adopted a different approach. Instead of relying on the search hub, you should:

Avoid specifying the search hub in API keys or search tokens, as the Commerce API automatically sets it. This simplifies authentication and aligns with best practices. For sensitive content, use source-level permissions rather than enforcing the search hub in API keys or tokens.

For more information, see Authenticate commerce requests.

The concept of context existed in the search engine through the Context controller. However, its meaning has evolved in the commerce engine.

With the search engine, context refers to injecting custom contextual information into search requests and usage analytics events sent from a search interface. With the commerce engine, context represents the state of the user’s session. This includes details such as the current URL, selected currency, language, country code, and other relevant information.

After configuring the appropriate query pipeline conditions, ensure that you send the correct context data using the commerce engine. Doing so helps target the correct query pipeline.

The context state is managed by the engine. It’s initialized during engine initialization and updated through the Context controller as users interact with the storefront.

Most importantly, when users navigate between pages, update the context to reflect the current URL.

The cart is a new concept introduced in the commerce engine that didn’t exist in the search engine.

Manage the user’s cart state using the commerce engine. Initialize the engine with the cart state, modify the cart through the Cart controller, and save the cart state to persist across sessions or page navigation.

This approach ensures that actions such as adding or removing products, adjusting quantities, or completing purchases emit the appropriate cart and purchase events for analytics.

For more information, see Managing the cart.

Whereas the search engine allowed you the choice of using the older Coveo UA Protocol versus the newer Event Protocol, the Commerce engine only supports the latest Event Protocol.

For a Coveo for Commerce implementation, you should use the dedicated Headless controllers to send analytics events. There are four client-side events you need to send as users interact with your storefront: