Create search configurations (legacy)

This is for:

Developer
Important

This article covers the legacy Search Configurations API. The Coveo Platform no longer uses search configurations to configure queries or define rules.

This functionality has been replaced as follows:

For now, the global endpoints of the Search Configurations API (/rest/organizations/<ORGANIZATION_ID>/commerce/v2/configurations/search/global) are still available.

You don’t need to create a global query configuration before querying products from a search interface. However, you can create a global query configuration to specify the facets, sorts, and additional fields that apply when your front end queries the Commerce API.

Previously, you could use specific search configurations to define which rules should apply to queries. However, you can no longer define rules programmatically.

The global query configuration is important in the context of search because, unlike product listing pages (PLPs), which are preconfigured based on a known set of products, search is much more responsive. It’s impossible to know what a user will query for, which means the global query configuration will be leveraged for most, if not all, queries.

Use the global search configuration endpoints

A global query configuration is a JSON object that follows a specific format. You can modify global query configurations by calling the Search Configurations API endpoints and providing a configuration JSON.

The following is a sample global query configuration JSON:

{
  "trackingId": "<TRACKING ID>", 1
  "name": "GLOBAL",
  "conditions": [], 2
  "queryConfiguration": { 3
      "additionalFields": [
          "color",
          "size"
      ],
      "facets": { 4
          "enableIndexFacetOrdering": false,
          "freezeFacetOrder": true,
          "facets": [
              {
                  "type": "numericalRange",
                  "facetId": "ec_price",
                  "field": "ec_price",
                  "displayNames": [
                      {
                          "value": "Price",
                          "language": "en"
                      }
                  ]
              },
              {
                  "type": "regular",
                  "facetId": "cf_product_type",
                  "field": "cf_product_type",
                  "displayNames": [
                      {
                          "value": "Product Type",
                          "language": "en"
                      }
                  ]
              },
              {
                  "type": "hierarchical",
                  "facetId": "ec_category",
                  "field": "ec_category",
                  "displayNames": [
                      {
                          "value": "Category",
                          "language": "en"
                      }
                  ],
                  "delimitingCharacter": "|"
              }
          ]
      },
      "perPage": 15,
      "sorts": [
          {
              "sortCriteria": "relevance"
          },
          {
              "sortCriteria": "fields",
              "fields": [
                  {
                      "field": "ec_promo_price",
                      "direction": "desc",
                      "displayNames": [
                          {
                              "value": "Price (High to Low)",
                              "language": "en"
                          }
                      ]
                  }
              ]
          }
      ]
  },
  "scope": "global" 5
}
1 The trackingId lets you segregate your configurations. When you make a request via the Commerce API to retrieve this configuration, you’ll need to specify the tracking ID to retrieve the configuration.
2 conditions lets you specify the conditions under which this configuration applies. For the global configuration, these are left empty.
3 queryConfiguration lets you specify which facets, sort criteria, and additional fields you want to be returned for this configuration.
4 Only use the facets property if you’re managing facets directly via the Commerce API. If you’re using the Coveo Merchandising Hub (CMH), use the Facet manager instead.
Important

The Facet manager in the CMH is currently in open beta. If you gained access to the CMH before the Facet manager was available and would like to adopt it, contact your Coveo representative.
5 The scope of the configuration. This must be set to global.

For more details on all the possible parameters, see the reference documentation.

Specific search configurations

The Coveo Platform no longer supports specific search configurations. When you use any Search Configurations API endpoints (apart from the global ones), you’ll get an error.

Instead, create and manage your query rules in the Coveo Merchandising Hub (CMH).