--- title: Migrating from search engine to commerce engine slug: oc2a0438 canonical_url: https://docs.coveo.com/en/oc2a0438/ collection: coveo-for-commerce source_format: adoc --- # Migrating from search engine to commerce engine If your current implementation uses the standard [Headless search engine](https://docs.coveo.com/en/headless/latest/reference/modules/Search.html), it relies on the Search API. For new Coveo for Commerce implementations, you should use the Commerce API. This means you'll need to use the [commerce engine](https://docs.coveo.com/en/o52e9091/) in Headless. While the search engine and commerce engine share similar basic principles, there are important differences in how they function. This guide explains those differences and provides steps to help you migrate from the search engine to the commerce engine. ## Sub-controllers and dedicated Commerce API routes With the Search API, you make a POST request to the Search API endpoint: ```text https://platform.cloud.coveo.com/rest/search/v2?organizationId= ``` Depending on the parameters specified in the request body, the API processes either a [search request](https://docs.coveo.com/en/114/) or a [recommendation request](https://docs.coveo.com/en/1447/). 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](https://docs.coveo.com/en/103/), each [product discovery solution](https://docs.coveo.com/en/o9cf0524/) has its own dedicated route: ```text https://platform.cloud.coveo.com/rest/organizations//commerce/v2/search https://platform.cloud.coveo.com/rest/organizations//commerce/v2/listing https://platform.cloud.coveo.com/rest/organizations//commerce/v2/recommendations ``` In Headless, the Commerce API is integrated by initializing a single commerce engine instance and then creating dedicated [sub-controllers](https://docs.coveo.com/en/o6r70022#interact-with-a-controller) to target the desired product discovery endpoint. ## Prescriptive vs descriptive requests 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](https://docs.coveo.com/en/o5290573/). 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](https://docs.coveo.com/en/o6od0220/). ## Authenticating requests and routing queries Previously, implementations using the Search API and search engine targeted the appropriate [query pipeline](https://docs.coveo.com/en/180/) by creating specific [query pipeline conditions](https://docs.coveo.com/en/2793/) based on the incoming [search hub](https://docs.coveo.com/en/1342/) 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](https://docs.coveo.com/en/3143/), implementations added a [query pipeline filter](https://docs.coveo.com/en/3180#method-1-use-a-query-parameter-rule-recommended) 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: * Configure the required [storefront associations](https://docs.coveo.com/en/o48e0216/). When you define a [storefront](https://docs.coveo.com/en/p33g0410/) association, the [Coveo Platform](https://docs.coveo.com/en/186/) will automatically create three [query pipelines](https://docs.coveo.com/en/180/) and their associated [conditions](https://docs.coveo.com/en/2793/), one for each [product discovery solution](https://docs.coveo.com/en/o9cf0524/). > **Note** > > If these [query pipelines](https://docs.coveo.com/en/180/) already exist for a given [tracking ID](https://docs.coveo.com/en/o8rb0139/), then the [Coveo Platform](https://docs.coveo.com/en/186/) won't create duplicates. > > For example, if your [storefront](https://docs.coveo.com/en/p33g0410/) consists of a single site with multiple language and currency options, you'll associate multiple [locales](https://docs.coveo.com/en/p4tf0351/) with a single [tracking ID](https://docs.coveo.com/en/o8rb0139/). > In this case, the [Coveo Platform](https://docs.coveo.com/en/186/) will only create these [query pipelines](https://docs.coveo.com/en/180/) for the first [storefront](https://docs.coveo.com/en/p33g0410/) association that you define with this [tracking ID](https://docs.coveo.com/en/o8rb0139/). * Ensure that the correct tracking ID ([set on engine initialization](https://docs.coveo.com/en/o6r70022#initialize-the-headless-commerce-engine)) and [context](#initializing-and-managing-context-including-url-state) are sent from the front-end. Avoid specifying the [search hub](https://docs.coveo.com/en/1342/) 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](https://docs.coveo.com/en/o8ld0051/). ## Initializing and managing context, including URL state The concept of _context_ existed in the search engine through the [Context](https://docs.coveo.com/en/headless/latest/reference/interfaces/Commerce.Context.html) 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 [storefront associations](https://docs.coveo.com/en/o48e0216/), ensure that you send the correct context data using the commerce engine. Doing so helps target the correct [query pipeline](https://docs.coveo.com/en/180/). The context state is managed by the engine. It's initialized during [engine initialization](https://docs.coveo.com/en/o6r70022#initialize-the-headless-commerce-engine) and updated through the [Context](https://docs.coveo.com/en/headless/latest/reference/interfaces/Commerce.Context.html) controller as users interact with the [storefront](https://docs.coveo.com/en/p33g0410/). Most importantly, when users [navigate between pages](https://docs.coveo.com/en/o7v87331/), update the context to reflect the current URL. ## Managing cart state 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](https://docs.coveo.com/en/o7v87042/). ## Tooling for sending analytics events 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 Relay controllers to send analytics events. There are four client-side events to send as users interact with your storefront: * [Click events](https://docs.coveo.com/en/o1n92447#capture-a-click-event-using-relay) * [Product view events](https://docs.coveo.com/en/o1n93101#capture-a-product-view-event-using-relay) * [Cart events](https://docs.coveo.com/en/o1n93466#capture-a-cart-event-using-relay) * [Purchase events](https://docs.coveo.com/en/o1n93059#capture-a-purchase-event-using-relay)