Coveo Merchandising Hub implementation guide

This is for:

Merchandising Hub Implementer

The new Coveo Merchandising Hub (CMH) offers a convenient solution for ecommerce merchants to manage product discovery for their Coveo for Commerce implementation.

This new interface provides merchants with the flexibility to curate products displayed on search results pages, product listing pages, and recommendation slots, that are tailored to various scenarios and requirements.

To begin utilizing the CMH, your Coveo for Commerce implementation must be configured properly.

This article outlines the prerequisites for integrating the CMH seamlessly into your Coveo for Commerce setup.

General configuration

To utilize the CMH, specific configurations must be implemented in your Coveo organization via the Coveo Administration Console.

The following concepts are an essential part of the configuration, as well as creating an optimal experience within the CMH:

By understanding and leveraging these concepts, you’ll then be able to:

Product discovery solutions

The CMH allows merchandisers to manage the three product discovery solutions:

  • Search: The mechanisms that power visitor's query handling and result rendering.

  • Product listing: The mechanisms that power the display of products of a category or collection on a product listing page.

  • Recommendations: The mechanisms that power the display of products recommended to a visitor on a recommendations carousel, based on their behavior and preferences.

Tracking ID

A Coveo organization can serve many ecommerce sites or applications. It’s important to segregate the data gathered from each of these sites or applications to ensure personalized and relevant outputs from your Coveo Machine Learning models, as well as usable reporting, and clear merchandising actions.

To meet this requirement, the Coveo Platform uses the values of the tracking ID to differentiate usage analytics data by site or app. Therefore, you must assign a tracking ID for each of your Coveo-powered ecommerce storefronts.

Each storefront represents a distinct shopping experience with its own unique cart and checkout process. For example, if a visitor is browsing products on a site and their cart contents reset when accessing a new product, it indicates a switch in storefronts.

This tracking ID not only distinguishes data origins in usage analytics events, it’s also required to configure your query pipelines.

Examples

  • Your Coveo organization powers two brands: Barca sports and Barca parts. You operate only in Canada.

    Therefore, you have two different sites that require their own unique tracking ID:

    • barca_sports

    • barca_parts

  • Alternatively, you may have a single brand that operates in two different countries, United States and Canada. These storefronts each have their own cart and checkout mechanisms.

    Therefore, you would have to define a tracking ID for each of your storefronts, as follows:

    • barca_sports_us

    • barca_sports_ca

For more information, see Tracking ID.

Tracking ID for non-production environments

When you’re developing or testing your Coveo-powered ecommerce site or application, you’ll likely use a non-production Coveo organization.

If you have many non-production environments that are all powered by the same non-production organization, you’ll need to define a tracking ID for each website or application in each of these environments. For example, you may have a development and a staging environment.

To ease identifying the tracking ID for each environment, we recommend using a naming convention that includes the environment name, such as barca_sports_dev.

Example

You have a non-production Coveo organization, to test the behavior of two sites, Barca sports and Barca parts.

Your non-production organization powers two different non-production environments: development and staging.

Therefore, you would have to define a tracking ID for each of your ecommerce sites or applications in each of these environments, as follows:

  • barca_sports_dev

  • barca_sports_staging

  • barca_parts_dev

  • barca_parts_staging

Query pipeline configuration

To ensure that the CMH works seamlessly with your Coveo for Commerce implementation, you must configure your query pipelines to support the product discovery solutions that you want to manage through the CMH.

Query pipelines must be created in accordance with the number of tracking IDs that the CMH will support. This means that for each tracking ID, you must create a query pipeline for each product discovery solutions that you’re using.

Query pipelines must follow a strict naming convention, as well as a specific description, which are as follows:

  • Query pipeline name: cmh-<solution>-<tracking-id>

  • Query pipeline description: <solution>-<tracking-id>

Where:

Example

Your Coveo organization powers the Barca sports Coveo-powered commerce implementation.

You operate in two different countries: United States and Canada.

Therefore, you have two tracking IDs:

  • barca_sports_us

  • barca_sports_ca

This means that you would have to create the following query pipelines:

Tracking ID Product discovery solution Query pipeline name Query pipeline description

barca_sports_us

Search

cmh-search-barca_sports_us

search-barca_sports_us

Product listing

cmh-product-listing-barca_sports_us

product-listing-barca_sports_us

Recommendations

cmh-recommendations-barca_sports_us

recommendations-barca_sports_us

barca_sports_ca

Search

cmh-search-barca_sports_ca

search-barca_sports_ca

Product listing

cmh-product-listing-barca_sports_ca

product-listing-barca_sports_ca

Recommendations

cmh-recommendations-barca_sports_ca

recommendations-barca_sports_ca

Query pipeline conditions

For queries originating from the different product discovery solution interfaces to be routed to the correct query pipeline, your must configure query pipeline conditions.

Query pipeline conditions are elements that determine which query pipeline to use based on the product discovery solution the end user is interacting with. For example, if a user is interacting with the search interface, the query pipeline condition will route the query to the query pipeline dedicated to search.

In the context of the CMH, query pipeline conditions are built with values of parameters sent to the Commerce API when requesting products using the different endpoints. See Consuming the Commerce API for more information about the endpoints available in the Commerce API.

Query pipeline conditions must follow a strict naming convention. The naming convention differs based on the product discovery solution that the query pipeline condition supports. The following table provides the naming convention for each product discovery solution:

Product discovery solution Naming convention

Search

Search Hub is Search and Context[website] is <trackingId>

Product listing

Search Hub is Listing and Context[website] is <trackingId>

Recommendations

Search Hub is Recommendations and Context[website] is <trackingId>

Where <trackingId> is the value of the tracking ID parameter as used in the request to the Commerce API. For example, when requesting products for your kayaks listing page, the value sent in the trackingId parameter is barca_sports_ca. Therefore, the value of the <trackingId> will be barca_sports_ca. See Tracking ID for more information about how to define tracking IDs.

Example

For the barca_sports_ca tracking ID, you created the following query pipelines:

  • Search query pipeline: cmh-search-barca_sports_ca

  • Listing query pipeline: cmh-product-listing-barca_sports_ca

  • Recommendations query pipeline: cmh-recommendations-barca_sports_ca

The following table provides the query pipeline conditions that you would have to create for each query pipeline:

Product discovery solution Query pipeline Query pipeline condition

Search

cmh-search-barca_sports_ca

Search Hub is Search and Context[website] is barca_sports_ca

Product listing

cmh-product-listing-barca_sports_ca

Search Hub is Listing and Context[website] is barca_sports_ca

Recommendations

cmh-recommendations-barca_sports_ca

Search Hub is Recommendations and Context[website] is barca_sports_ca

For instructions on how to create query pipeline conditions, see Manage query pipeline conditions.

Machine learning models for Coveo for Commerce

Coveo recommends that you configure Coveo Machine Learning (Coveo ML) models to power and enhance product discovery experiences. To increase personalization and relevancy, configure the recommended Coveo ML models for each of the product discovery solutions:

Product discovery solution Recommended model

Search

Automatic Relevance Tuning (ART) (optimized for search)

Intent-Aware Product Ranking (IAPR) (optional)

Predictive Query Suggestions (PQS) or Query Suggestions (QS)

Dynamic Navigation Experience (DNE)

Listing

Automatic Relevance Tuning (ART) (optimized for listing pages)

Recommendations

Product Recommendations (PR)

To configure the Coveo ML models for product discovery solutions:

  1. Configure the appropriate models for each product discovery solution.

    Note

    For optimal results, we recommend that you configure one model of each type for each tracking ID that you’ve defined.

  2. Associate the models with the query pipelines that you’ve created.

  3. For ART, QS, DNE, and PR models, configure learning filters to ensure that the model only uses the data that’s relevant to the website on which it’s deployed.

Example

You’ve defined the following tracking IDs for your two Coveo-powered ecommerce sites or applications:

  • barca_sports_us

  • barca_sports_ca

Therefore, you create the following Coveo Machine Learning models:

Tracking ID Product discovery solution Model name

barca_sports_us

Search

Barca Sports US Search IAPR model

Barca Sports US Search PQS model

Barca Sports US Search DNE model

Listing

Barca Sports US Listing ART model

Recommendations

Barca Sports US Product Recommendations PR model

barca_sports_ca

Search

Barca Sports CA Search IAPR model

Barca Sports CA Search PQS model

Barca Sports CA Search DNE model

Listing

Barca Sports CA Listing ART model

Recommendations

Barca Sports CA Product Recommendations PR model
Note

To effectively power commerce-optimized Coveo ML models, substantial usage analytics data is needed. Proper data tracking implementation is crucial for feeding models the required data, enhancing relevance over time as more data is collected.

Machine learning model configuration for commerce

When using an ART, QS, DNE, or PR model for a Coveo for Commerce Coveo organization that powers multiple tracking IDs, you must configure learning filters to ensure that the model uses only the data that’s relevant to the website on which it’s deployed.

For example, if your Coveo for Commerce organization powers multiple websites, you must configure learning filters to ensure that the model only learns from the data of the website on which it’s deployed.

Note

For IAPR and PQS models, instead of defining learning filters, you’ll be required to configure the model to use the appropriate tracking IDs.

Configure the model to use the appropriate tracking ID

To configure learning filters:

  1. Once you’ve created your model, access the Models (platform-ca | platform-eu | platform-au) page.

  2. Click the desired model, and then click More > Edit JSON in the Action bar.

  3. In Edit a Model JSON Configuration, add the following commonFilter object to the JSON configuration:

    "commonFilter": "(c_context_website=@'<TRACKING-ID>')"

    Where you replace <TRACKING-ID> with the tracking ID defined for the website on which you want to use the model.

  4. Click Save.

Example

If you have a model that you want to use on a website for which the tracking ID is barca_sports_us, your JSON configuration should look like this:

{
    "modelDisplayName": "My Commerce ML Model",
    "exportPeriod": "P3M",
    "intervalTime": 1,
    "intervalUnit": "WEEK",
    "commonFilter": "(c_context_website=@'barca_sports_us')",
    "exportOffset": "PT0S"
}

Index commerce data

To make your product inventory available in the Coveo Platform ecosystem, and manageable through the CMH, you need to add your product content to the index. Typically, this content is stored in repositories such as product information management systems (PIMs) and digital asset management systems (DAMs) in your own ecosystem.

To ensure a successful Coveo for Commerce implementation, it’s necessary to aggregate and format this content in a way that can be read and understood by the Coveo Platform.

Once the content is formatted as required, it must be pushed to the index, specifically to a Catalog source. You must then create and configure a commerce catalog to establish the relationship between indexed items.

This section provides an overview of the steps required to prepare your product content for indexing and to configure your commerce catalog.

Catalog source

A Catalog source is a virtual container within the Coveo Platform that holds all the products that you want to make available to customers.

It must be created in your Coveo organization to be able to index your product content.

Tip
Leading practice

We recommend creating a Catalog source per locale you support.

For example, if you support the following locales:

  • en-US-USD

  • en-CA-CAD

  • fr-CA-CAD

You would have to create three Catalog sources.
Note

The Coveo Platform also offers connectors for indexing Commerce content from SAP and Salesforce Commerce Cloud. For more information, see:

For instructions on how to create a Catalog source, see Create a Catalog source.

Commerce fields

When you create a Catalog source, a list of standard commerce fields is automatically generated in your Coveo organization. You can access them by navigating to the Fields (platform-ca | platform-eu | platform-au) page in the Coveo Administration Console. These commerce-related fields are prefixed with ec_ (for example, ec_price).

It’s essential to populate the Coveo for Commerce standard fields to optimize your implementation. These commerce-related fields store vital metadata on your products, such as price, name, and description. Also, Coveo ML models use the values from these fields to create product vectorization and improve content analysis.

In addition to these standard fields, you must also create a list of fields that will be used to configure your commerce catalog later on.

You’ll also likely need to create additional fields to store more specific metadata for your products. For example, if you sell shoes, you’ll likely want your products to contain information such as gender, style, and collection, or your product variations to contain information such as size and width.

For detailed reference on the standard commerce fields and how to create additional fields, see Commerce fields.

Index field mapping

While standard commerce fields are automatically created in your Coveo organization, they’re not filled with the expected values by default. This also applies to the additional fields you create to store more specific metadata for your products.

You’ll need to map the relevant product metadata (that exists on your product) to these fields to make sure that your product attributes are correctly represented in the index.

For detailed information on how to establish commerce field mapping, see Map commerce fields.

Important

While field mapping is essential to ensure that your product content is correctly represented in the index, another mapping procedure is essential for Coveo Machine Learning models to work effectively and to enable accurate reporting.

This mapping procedure is done when configuring your product catalog.

Catalog objects

Your product content must be formatted in a way that can be read and understood by the Coveo Platform. More precisely, this means that your content must be formatted as items of the correct type of catalog object.

A Catalog source can contain items of three different types of catalog object: Product, variant, and availability. When indexing your product content, you must ensure that the items you’re indexing are correctly formatted as one of these three types of catalog objects.

Product: The product object represents individual searchable products in your inventory.

variant: In a catalog featuring product variants, customers are presented with a range of displayable products. However, when making a purchase, they can select a specific variation of that product. A variant can be seen as the sellable version of a product. Therefore, each sellable variation of the product must be indexed as an item of the variant object type.

It’s important to note that a variant isn’t a displayable product, but rather a unique non-displayable version of a product. Therefore, variants can’t be displayed in search results, product listing pages, or recommendation carousels. Instead, they’re used to represent different variations of a single product, such as different sizes, which can be used to filter results on search results and product listing pages.

Availability: If your product offering differs depending on store availability, price lists, or anything that controls which user has access to certain products or variants, you can use the availability object. For example, you’ll need to index an item of the availability object type for each store products are available in.

For more information on the different catalog objects, as well as instructions on how to configure related items see catalog object types.

About product grouping

While variants may sound like the best catalog object to use to represent different variations of a single product, your use case may require the usage of product grouping.

variants represent unique non-displayable versions of a product. For example, a pair of shoe may come in different sizes and widths. Each variation in size and width would be a variant of the shoe.

Product grouping, on the other hand, is used to group similar products together. It’s particularly useful in an ecommerce setting where you want to showcase variations of a product, such as different colors or styles. For example, a kayak may come in different colors, and you would want to showcase all the colors on the same product page.

For more information and examples on the usage of variants and product grouping, see Understanding the difference between variants and product groupings.

Index your product content

Once your product content is formatted and ready to be indexed, you must push it to the index.

Refer to Stream your catalog data to your source for detailed instructions on how to index your product content into your Catalog source.

Configure your product catalog

Once your product content is indexed, you must configure your product catalog to establish the relationship between indexed items.

The Catalogs (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console lets you create catalog configurations that establish the relationship between indexed items, their variants, and corresponding availabilities. The catalog also lets you standardize your data to enable the proper use of Coveo ML models. Therefore, its creation is essential for using Coveo ML and Coveo Usage Analytics capabilities.

There’s a 1:1 relationship between your commerce catalog and the product source, which means your product source can only be used in one commerce catalog. As a best practice, you should have a commerce catalog per product source.

Example

If you support the following locales:

  • en-US-USD

  • en-CA-CAD

  • fr-CA-CAD

You would have to create three Catalog sources and three commerce catalogs.

For detailed information on how to configure your product catalog, see Commerce catalog.

About standard commerce fields catalog mapping

The Standard fields section of the Catalogs (platform-ca | platform-eu | platform-au) page lets you map the standard commerce fields to the metadata available in your source.

While you may have already defined index mapping rules, as explained in the Index field mapping section, you must also define mapping rules for the standard commerce fields in the Catalogs (platform-ca | platform-eu | platform-au) page.

This allows Coveo Personalization-as-you-go models to effectively use the values from these fields to create product vectorization, as well as ensuring accurate reporting.

Data tracking

Coveo for Commerce is a data-driven solution that leverages usage analytics data to provide personalized and relevant product discovery experiences.

usage analytics data is vital to the relevance of your experience on the platform. You’ll use data to create and enhance the user experience through Coveo Machine Learning models, as well as to track the performance of your product discovery solutions directly in the CMH.

Therefore, it’s crucial to ensure that your ecommerce site or application is sending the necessary usage analytics events to the Coveo Platform.

To track usage analytics events in your ecommerce site or application, the Coveo Platform offers two protocols:

Note

The Event Protocol is the recommended way to track usage analytics events in your ecommerce site or application.

If you’re currently using the Coveo UA library, reach out to your Customer Success Manager (CSM) for details on how to adopt the Event Protocol.

These libraries allow you to track the usage analytics events that are required to get a fully functional Coveo for Commerce implementation:

  • Products views: Every time a Product detail page (PDP) loads, a product view event must be sent to the Coveo Platform.

  • Cart actions: Every time a product is added to or removed from the cart, a cart action event must be sent to the Coveo Platform.

  • Purchases: Every time a purchase is made, a purchase event must be sent to the Coveo Platform.

  • Product clicks: Every time a product is clicked, either from a search result, a product listing page, or a recommendations carousel, a product click event must be sent to the Coveo Platform.

About data validation

Capturing commerce events allows you to trace a user’s journey through your Coveo-powered commerce solution by gathering data on the interactions with various elements. Validation is a critical process that ensures the integrity and effectiveness of the logged data by verifying the events have been implemented correctly.

For more information about data validation, see Data validation.

User interface integration

To deploy Coveo Platform's search and product listing management capabilities on your ecommerce site or application, you must build user interfaces that leverage the Coveo Commerce API. You’ll then be able to manage product listing pages and search behavior through the CMH.

This section provides an overview of the different ways to access these endpoints, including direct interactions with the Commerce API, or with the Coveo Headless library.

You’ll also find information about the endpoints you’ll need to interact with to retrieve products from a product listings page, request query suggestions, and execute queries against your index.

Consuming the Commerce API

Coveo offers different ways to build user interfaces.

To get a functional Coveo-powered ecommerce site or application, you must build user interfaces that leverage the Coveo Commerce API. The various endpoints of the Coveo Commerce API can be accessed in different ways:

  • Using the Coveo Commerce API directly

  • Through the Coveo Headless framework

While using the Commerce API directly allows for more flexibility, using the Coveo Headless library can simplify the process of integrating the Commerce API into your ecommerce site or application. To build your UI commerce components using the API directly, refer to the API documentation:

Coveo Headless framework

Important

Commerce API compatible Headless controllers are being developed to ease the development of the UI interfaces that must interact with the Commerce API. To get early access to these, reach out to your Coveo Customer Success Manager (CSM).

The Coveo Headless library serves as a toolkit for developing Coveo-powered UI components like search boxes, search result pages, and product listing pages. Acting as a middleware for applications, it eases communication between UI elements and the Coveo Platform.

This library abstracts the complexities of Coveo APIs without sacrificing flexibility. It’s compatible with any web development framework and and autonomously manages the state of your search and listing pages. Rather than offering prebuilt UI components, it provides an extendable set of reducers and controllers, allowing you to seamlessly connect your custom search UI components to Coveo APIs.

Coveo Commerce API endpoints

The Coveo Commerce API provides a set of endpoints that allow you to execute queries, request query suggestions, and retrieve products from your index.

The endpoints you’ll have to use are:

  • The search endpoint

  • The querySuggest endpoint

  • The listing endpoint

Important

Requests to the Commerce API must be authenticated using either an API key or a search token.

While you can use an API key to authenticate requests to the Commerce API, we recommend using a search token for enhanced security and flexibility.

Search tokens automatically expire after 24 hours, limiting unauthorized use. Additionally, search tokens offer precise control over access to specific products, prices, or content, ensuring only authorized users see relevant information.

While setting up tokens may involve more initial effort than generating API keys, it provides tailored access control and safeguards sensitive content. However, if your use case doesn’t require user-specific content or enhanced security through token expiration, API keys may suffice.

For information on how to configure a search token, see Use search token authentication.

For information on how to configure an API key, see API key for search.

The Search endpoint

The search endpoint returns a list of products based on a query, tracking ID, and a set of filters.

For the complete reference API documentation for the search endpoint, as well as request samples, see Execute a search query.

For a successful request, the search endpoint returns a response containing the list of products that match the query, along with the facets, pagination, and sorting information like in the following example:

{
  "responseId": "bcd89a1d-4599-4e1e-a3d0-9c1f0852d6f3",
  "products": [
    {
      "additionalFields": {},
      "ec_name": "Okeanos Kayak",
      "ec_description": "Okeanos Kayak SP01014_00002 This orange sea kayak is perfect for beginner and experienced kayakers.",
      "ec_shortdesc": "Okeanos Kayak SP01014_00002 This orange sea kayak is perfect for beginner and experienced kayakers.",
      "ec_brand": "Okeanos",
      "ec_category": [],
      "ec_thumbnails": [],
      "ec_images": [
        "https://sports.barca.group/okeanos-kayak.jpg"
      ],
      "ec_price": 1400,
      "ec_promo_price": 1275,
      "ec_in_stock": null,
      "ec_cogs": null,
      "ec_item_group_id": null,
      "ec_rating": 4.5,
      "ec_product_id": null,
      "ec_gender": null,
      "ec_color": null,
      "ec_listing": "",
      "clickUri": "https://sports.barca.group/pdp/SP01014_00002?model=SP01014",
      "permanentid": "SP01014_00002",
      "childResults": [],
      "totalNumberOfChildResults": 0,
      "documentUri": "https://sports.barca.group/pdp/SP01014_00002?model=SP01014",
      "documentUriHash": "1G0eR633piñuKDE3"
    },
    {
      "additionalFields": {},
      "ec_name": "Sea Kayaker Yellow",
      "ec_description": "This kayak is perfect for exploring the beautiful waters of the Yellow Sea.",
      "ec_shortdesc": "This kayak is perfect for exploring the beautiful waters of the Yellow Sea.",
      "ec_brand": "Barca",
      "ec_category": [],
      "ec_thumbnails": [],
      "ec_images": [
        "https://sports.barca.group/sea-kayaker.jpg"
      ],
      "ec_price": 1600,
      "ec_promo_price": 1350,
      "ec_in_stock": null,
      "ec_cogs": null,
      "ec_item_group_id": null,
      "ec_rating": 4.5,
      "ec_product_id": null,
      "ec_gender": null,
      "ec_color": null,
      "ec_listing": "",
      "clickUri": "https://sports.barca.group/pdp/SP01006_00004?model=SP01006",
      "permanentid": "SP01006_00004",
      "childResults": [],
      "totalNumberOfChildResults": 0,
      "documentUri": "https://sports.barca.group/pdp/SP01006_00004?model=SP01006",
      "documentUriHash": "4G0eR792puñrKDZ3"
    },
  ],
  "facets": [
    {
      "type": "regular",
      "facetId": "color",
      "field": "color",
      "displayName": "Color",
      "moreValuesAvailable": true,
      "fromAutoSelect": false,
      "values": [
        {
          "state": "idle",
          "numberOfResults": 52,
          "value": "Blue"
        },
        {
          "state": "idle",
          "numberOfResults": 12,
          "value": "Black"
        },
        {
          "state": "idle",
          "numberOfResults": 2,
          "value": "Brown"
        },
        {
          "state": "idle",
          "numberOfResults": 37,
          "value": "Gray"
        },
        {
          "state": "idle",
          "numberOfResults": 5,
          "value": "White"
        },
        {
          "state": "idle",
          "numberOfResults": 7,
          "value": "Beige"
        },
        {
          "state": "idle",
          "numberOfResults": 41,
          "value": "Multi"
        },
        {
          "state": "idle",
          "numberOfResults": 44,
          "value": "Green"
        }
      ],
      "fieldExpanded": false
    },
    {
      "type": "numericalRange",
      "facetId": "ec_promo_price",
      "field": "ec_promo_price",
      "displayName": "Price",
      "moreValuesAvailable": false,
      "fromAutoSelect": false,
      "values": [
        {
          "state": "idle",
          "numberOfResults": 89,
          "start": 0,
          "end": 10,
          "endInclusive": true
        },
        {
          "state": "idle",
          "numberOfResults": 463,
          "start": 10,
          "end": 20,
          "endInclusive": true
        },
        {
          "state": "idle",
          "numberOfResults": 1029,
          "start": 20,
          "end": 50,
          "endInclusive": true
        },
        {
          "state": "idle",
          "numberOfResults": 434,
          "start": 50,
          "end": 100,
          "endInclusive": true
        },
        {
          "state": "idle",
          "numberOfResults": 80,
          "start": 100,
          "end": 250,
          "endInclusive": true
        }
      ],
      "fieldExpanded": false
    }
  ],
  "pagination": {
    "page": 0,
    "perPage": 32,
    "totalCount": 2063,
    "totalPages": 65
  },
  "sort": {
    "appliedSort": {
      "sortCriteria": "relevance"
    },
    "availableSorts": [
      {
        "sortCriteria": "relevance"
      },
      {
        "sortCriteria": "fields",
        "fields": [
          {
            "field": "ec_promo_price",
            "direction": "desc",
            "displayName": "Price (High to Low)"
          }
        ]
      },
      {
        "sortCriteria": "fields",
        "fields": [
          {
            "field": "ec_promo_price",
            "direction": "asc",
            "displayName": "Price (Low to High)"
          }
        ]
      }
    ]
  },
  "executionReport": null
}

The Query Suggestion endpoint

The querySuggest endpoint generates query suggestions and autocompletions.

Note

query suggestions can only be generated if a Coveo Machine Learning query suggestions or predictive query suggestions model is enabled and active in the query pipeline to which queries are sent.

For the complete reference documentation for the querySuggest endpoint, as well as request samples, see Request query suggestions.

For a successful request, the querySuggest endpoint returns a response containing the list of query suggestions that match the query, like in the following example:

{
  "completions" : [ {
    "expression" : "kayak",
    "score" : 1085.3192443847656,
    "highlighted" : "{kay}[ak]",
    "executableConfidence" : 1.0,
    "objectId" : "f7d44aa3-8080-5ea3-9bba-9f5c8b6be209"
  },
  {
    "expression" : "tandem kayak",
    "score" : 85.31924438476562,
    "highlighted" : "[tandem] {kay}[ak]",
    "executableConfidence" : 1.0,
    "objectId" : "57fc4997-68aa-554b-bec2-81f7767c7cb2"
  },
  {
    "expression" : "fiberglass kayak paddle",
    "score" : 84.9081974029541,
    "highlighted" : "[fiberglass] {kay}[ak] [paddle]",
    "executableConfidence" : 1.0,
    "objectId" : "e3b08b76-bef9-51db-a76d-a240edbe29c5"
  },
  {
    "expression" : "kayak paddle",
    "score" : 84.25607109069824,
    "highlighted" : "{kay}[ak] [paddle]",
    "executableConfidence" : 1.0,
    "objectId" : "e7de6d9d-d9b2-57c0-86c4-53dc1c5f52d5"
  },
  {
    "expression" : "eco kayak paddle",
    "score" : 83.85774612426758,
    "highlighted" : "[eco] {kay}[ak] [paddle]",
    "executableConfidence" : 1.0,
    "objectId" : "6e852809-2397-5469-89d8-24aaf0809bf4"
  } ],
  "responseId" : "bff5bc58-3773-4078-8665-46ea6c1f634d"
}

The Listing endpoint

The listing endpoint generates a listing query to return a list of products based on a tracking ID and a URL.

For the complete reference documentation for the listing endpoint, as well as request samples, see Get a listing page.

For a successful request, the listing endpoint returns a response containing the list of products that match the listing query, along with the facets, pagination, and sorting information like in the following example:

{
  "responseId": "bcd89a1d-4599-4e1e-a3d0-9c1f0852d6f3",
  "products": [
   {
      "additionalFields": {},
      "ec_name": "Okeanos Kayak",
      "ec_description": "Okeanos Kayak SP01014_00002 This orange sea kayak is perfect for beginner and experienced kayakers.",
      "ec_shortdesc": "Okeanos Kayak SP01014_00002 This orange sea kayak is perfect for beginner and experienced kayakers.",
      "ec_brand": "Okeanos",
      "ec_category": [],
      "ec_thumbnails": [],
      "ec_images": [
        "https://sports.barca.group/okeanos-kayak.jpg"
      ],
      "ec_price": 1400,
      "ec_promo_price": 1275,
      "ec_in_stock": null,
      "ec_cogs": null,
      "ec_item_group_id": null,
      "ec_rating": 4.5,
      "ec_product_id": null,
      "ec_gender": null,
      "ec_color": null,
      "ec_listing": "",
      "clickUri": "https://sports.barca.group/pdp/SP01014_00002?model=SP01014",
      "permanentid": "SP01014_00002",
      "childResults": [],
      "totalNumberOfChildResults": 0,
      "documentUri": "https://sports.barca.group/pdp/SP01014_00002?model=SP01014",
      "documentUriHash": "1G0eR633piñuKDE3"
    },
    {
      "additionalFields": {},
      "ec_name": "Sea Kayaker Yellow",
      "ec_description": "This kayak is perfect for exploring the beautiful waters of the Yellow Sea.",
      "ec_shortdesc": "This kayak is perfect for exploring the beautiful waters of the Yellow Sea.",
      "ec_brand": "Barca",
      "ec_category": [],
      "ec_thumbnails": [],
      "ec_images": [
        "https://sports.barca.group/sea-kayaker.jpg"
      ],
      "ec_price": 1600,
      "ec_promo_price": 1350,
      "ec_in_stock": null,
      "ec_cogs": null,
      "ec_item_group_id": null,
      "ec_rating": 4.5,
      "ec_product_id": null,
      "ec_gender": null,
      "ec_color": null,
      "ec_listing": "",
      "clickUri": "https://sports.barca.group/pdp/SP01006_00004?model=SP01006",
      "permanentid": "SP01006_00004",
      "childResults": [],
      "totalNumberOfChildResults": 0,
      "documentUri": "https://sports.barca.group/pdp/SP01006_00004?model=SP01006",
      "documentUriHash": "4G0eR792puñrKDZ3"
    }
  ],
  "facets": [
    {
      "type": "regular",
      "facetId": "ec_brand",
      "field": "ec_brand",
      "displayName": "Brand",
      "moreValuesAvailable": false,
      "fromAutoSelect": false,
      "values": [
        {
          "state": "selected",
          "numberOfResults": 13,
          "value": "Okeanos"
        },
        {
          "state": "idle",
          "numberOfResults": 2,
          "value": "Barca"
        },
        {
          "state": "idle",
          "numberOfResults": 37,
          "value": "Aqua Marina"
        },
        {
          "state": "idle",
          "numberOfResults": 22,
          "value": "Aqua Sports"
        }
      ],
      "fieldExpanded": false
    },
    {
      "type": "numericalRange",
      "facetId": "ec_price",
      "field": "ec_price",
      "displayName": "Price",
      "moreValuesAvailable": false,
      "fromAutoSelect": false,
      "values": [
        {
          "state": "selected",
          "numberOfResults": 13,
          "start": 1000,
          "end": 2000,
          "endInclusive": true
        }
      ],
      "fieldExpanded": false
    }
  ],
  "pagination": {
    "page": 0,
    "perPage": 30,
    "totalCount": 13,
    "totalPages": 1
  },
  "sort": {
    "appliedSort": {
      "sortCriteria": "fields",
      "fields": [
        {
          "field": "ec_price",
          "direction": "asc",
          "displayName": "Price (Low to High)"
        }
      ]
    },
    "availableSorts": [
      {
        "sortCriteria": "relevance"
      },
      {
        "sortCriteria": "fields",
        "fields": [
          {
            "field": "ec_price",
            "direction": "asc",
            "displayName": "Price (Low to High)"
          }
        ]
      }
    ]
  },
  "executionReport": null
}