Create listing configurations

This is for:

Developer

In this article

Manage listing pages using the Coveo Merchandising Hub
Using the listing configuration endpoints
Conflict between global and specific configurations
Using rule operators

You need to create a listing page configuration before you can query products from a product listing page (PLP).

There are two types of configurations: global and specific.

Global configuration: Define common elements that you want returned with each search, such as facets, sorting, additional fields, etc.
Specific configuration: Define a specific configuration for each PLP on your website to configure the Commerce API to only return products matching a certain criteria when you access a specific listing page.

Additionally, configurations can be also created to apply certain rules to your PLP pages, such as rules to rank products, pin certain products, and filter certain products.

You can create a listing page configuration in two ways:

Through the Coveo Merchandising Hub
Using the configuration endpoints directly (which the CMH uses under the hood)

Note

While the Coveo Merchandising Hub (CMH) provides an easy way to create or modify individual pages, interacting with the configuration endpoint is useful for batch creating or modifying listing pages, as you can script these calls.

Additionally, at this time, the CMH doesn’t let you configure facets, sorting, additional fields that should be returned with your query, or modify the global configuration. To do this, you’ll have to call the configuration endpoints directly.

Manage listing pages using the Coveo Merchandising Hub

The Coveo Merchandising Hub (CMH) allows merchandisers to create listing page configurations and manually curate the products shown via the Product listings manager.

Although Coveo ML models provide intelligent and personalized search results, the CMH lets you manually adjust the displayed products to meet your business needs.

For example, merchandisers can use the CMH to perform the following actions:

Create listing pages and decide which products to display.
Promote specific products on listing pages.
Pin promoted products to the top of listing pages.
Boost or bury products based on specific criteria.

To learn more about the CMH and how to use it, see Coveo Merchandising Hub (CMH).

Using the listing configuration endpoints

A listing configuration is a JSON object that follows a specific format. You can modify listing configurations by calling the configuration endpoints and providing a configuration JSON.

Global listing configuration

If all your listing pages share configuration details, such as common facets and sort criteria, place this information in the global configuration. This way, it’s returned by default without duplicating the information on each page.

Here is a sample global configuration:

{
    "name": "GLOBAL", 
    "trackingId": "<TRACKING_ID>", 
    "patterns": [ 
        {
            "url": "/"
        }
    ],
    "queryConfiguration": { 
        "additionalFields": [
            "color",
            "size"
        ],
        "facets": {
            "enableIndexFacetOrdering": false,
            "freezeFacetOrder": true,
            "facets": [
                {
                    "type": "hierarchical",
                    "facetId": "ec_category",
                    "field": "ec_category",
                    "displayNames": [
                        {
                            "value": "Category",
                            "language": "en"
                        }
                    ],
                    "delimitingCharacter": "|"
                },
                {
                    "type": "regular",
                    "facetId": "ec_colors",
                    "field": "ec_colors",
                    "displayNames": [
                        {
                            "value": "Color",
                            "language": "en"
                        }
                    ]
                },
                {
                    "type": "numericalRange",
                    "facetId": "ratings",
                    "field": "ec_rating",
                    "displayNames": [
                        {
                            "value": "Rating",
                            "language": "en"
                        }
                    ]
                }
            ]
        },
        "perPage": 48,
        "sorts": [
            {
                "sortCriteria": "relevance"
            },
            {
                "sortCriteria": "fields",
                "fields": [
                    {
                        "field": "ec_price",
                        "direction": "asc",
                        "displayNames": [
                            {
                                "value": "Price (Low to High)",
                                "language": "en"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    "rules": { 
        "rankingRules": [],
        "filterRules": [],
        "pinRules": []
    },
    "scope": "global" 
}

	The `name` of the listing page configuration. For the global configuration, it is always `GLOBAL`.
	The `trackingId` allows 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.
	Specify the `url` associated with the listing page configuration. This URL will also be used by the Commerce API on the front-end to retrieve this configuration. For the global configuration, it is always `/`.
	`queryConfiguration` allows you to specify which facets, sort criteria, and additional fields you want to be returned for this configuration.
	`rules` lets you specify the ranking rules, filter rules, or pin rules you want to apply to your page. For more details see Using rule operators.
	The scope of the configuration. This can be either specific or global, indicating whether the configuration is specific to a page or shared across multiple pages.

Specific listing configuration

Every PLP on your website will require a seperate listing configuration. This configuration defines the name and url of the listing page, along with which rules to apply to products return by the configuration.

Each specific configuration must have at least one filter rule as shown below.

{
    "name": "<NAME>", 
    "trackingId": "<TRACKING_ID>",
    "patterns": [ 
        {
            "url": "https://sports.barca.group/browse/surfboards"
        }
    ],
    "queryConfiguration": {}, 
    "rules": { 
        "rankingRules": [],
        "filterRules": [
            {
                "name": "Include product cat_slug contains surfboards",
                "essential": true,
                "locales": [],
                "filters": [
                    {
                        "fieldName": "cat_slug",
                        "operator": "contains",
                        "value": {
                            "type": "array",
                            "values": [
                                "surfboards"
                            ]
                        }
                    }
                ],
                "action": "include"
            }
        ],
        "pinRules": []
    },
    "scope": "specific"
}

	The `name` of the listing page configuration. This is also what appears in the CMH.
	Specify the `url` associated with the listing page configuration. This URL will also be used by the Commerce API on the front-end to retrieve this configuration.
	`queryConfiguration` allows you to specify which facets, sort criteria, and additional fields you want to be returned for this configuration. If these fields are left empty, the global configuration will be applied.
	`rules` lets you specify the ranking rules, filter rules, or pin rules you want to apply to your page. In this example, the page filters products that belong to the `surfboards` category. For more details see Using rule operators.

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

Conflict between global and specific configurations

As you can specify queryConfiguration and rules in both the global and the specific configuration, it’s important to understand how conflict is handled if they’re set in both places. Conflict resolution varies depending on the property in question.

Using `queryConfiguration` in both global and specific configurations

If you specify queryConfiguration in the global configuration and then omit it in a specific configuration, the global configuration will be used as a default.

If a specific configuration conflicts with a property in the global configuration, and the conditions of the specific configuration are met, then the property in the specific configuration takes precedence.

Example

Suppose you specify a numeric facet on ec_price in the global configuration and then a numeric facet on rating in a specific configuration for the "surfboards" query. The Commerce API returns the rating facet and not the ec_price facet when the user queries for "surfboards".

Using `rules` in both global and specific configurations

Within rules, you can’t set pinRules at all in the global configuration, but you can set rankingRules and filterRules.

For rankingRules and filterRules, if you set them in the global configuration and then omit them in a specific configuration, the global configuration will be used as a default. However, if these rules are set in both places, and a specific configuration is queried, these are merged.

Example

Suppose you boost "Blue" products in the global configuration using rankingRules. Next, you create a PLP page using filterRules to filter products that belong to the "surfboards" category. Now, when this PLP page is queried, it will return surfboards and additionally boost blue surfboards.

Using rule operators

There’s a list of predefined operators that merchandisers can use to scope rules to products whose attributes meet specific criteria.

If you’re using the Commerce API directly, you can specify rules in the JSON object that you send to the API. These rules can leverage any operator to target products based on their attributes.

For example, the following JSON showcases the use of two different operators:

{
  "name": "Operators Example",
  "trackingId": "sports",
  "patterns": [
    {
      "url": "https://sports-dev.barca.group/browse/promotions/clothing/pants"
    }
  ],
  "queryConfiguration": {
    "additionalFields": [
      "ec_rating"
    ],
    "facets": {
      "enableIndexFacetOrdering": false,
      "freezeFacetOrder": false,
      "facets": []
    },
    "perPage": 24,
    "sorts": []
  },
  "rules": {
    "filterRules": [ 
      {
        "filters": [ 
          {
            "fieldName": "cat_slug",
            "operator": "contains",
            "value": {
              "type": "array",
              "values": [
                "clothing/pants"
              ]
            }
          }
        ],
        "action": "include", 
        "essential": true, 
        "name": "Include products where cat_slug contains clothing/pants"
      }
    ],
    "rankingRules": [ 
      {
        "filters": [
          {
            "fieldName": "color",
            "operator": "isExactly",
            "value": {
              "type": "array",
              "values": [
                "blue"
              ]
            }
          }
        ],
        "value": 200,
        "action": "boost", 
        "name": "Boost blue products"
      }
    ],
    "pinRules": []
  },
  "scope": "specific"
}

	Create a `filterRules` object to specify the necessary inclusion rule for constructing a PLP.
	Define a `filters` object that utilizes the `contains` operator to include products where the `cat_slug` attribute contains `clothing/pants`.
	Specify the action that should occur when the rule is met. Filter rules can either `include` or `exclude` products. In this case, include the products.
	Ensure the `essential` attribute is set to `true`. Every listing page configuration must feature at least one `essential` filter rule that defines the products included in the listing page.
	Introduce a `rankingRules` object that uses the `isExactly` operator to boost products with the color `blue`.
	Indicate the action to take when the rule is met. Ranking rules can have either `boost` or `bury` actions. In this scenario, the products are boosted.

For a complete mapping of operator names to their Commerce API syntax, see the following table:

Operator Commerce API syntax

Operator	Commerce API syntax
Is	`isExactly`
Is not	`isExactlyNot`
Contains	`contains`
Does not contain	`doesNotContain`
Is defined	`isDefined`
Is not defined	`isNotDefined`
Is greater than (>)¹	`isGreaterThan`
Is less than (<)¹	`isLessThan`
Is greater than or equal to (≥)¹	`isGreaterThanOrEqualTo`
Is less than or equal to (≤)¹	`isLessThanOrEqualTo`

isExactly

isExactlyNot

contains

doesNotContain

isDefined

isNotDefined