Create listing configurations (legacy)

This is for:

Developer

In this article

Use the global listing configuration endpoints
Conflict between global and specific configurations
Using rule operators

This article covers the legacy Listing Configurations API. The Coveo Platform no longer uses listing configurations to configure product listing pages (PLPs) or define rules.

This functionality has been replaced as follows:

Listing pages are created individually using the Coveo Merchandising Hub (CMH) or in a batch using the Public Listing Page API.
Query configurations are managed through the dedicated Query Configurations API.
Rules are managed in the Coveo Merchandising Hub (CMH).

For now, the Listing Configurations API endpoints (/rest/organizations/<ORGANIZATION_ID>/commerce/v2/configurations/listings) are still available.

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

There are two types of listing configurations for PLPs: global and specific.

Global: Define common elements that you want returned with each search, such as facets, sorting, and additional fields.
Specific: 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.

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

Use the global listing configuration endpoints

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

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.

The following is a sample global listing configuration JSON:

{
    "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 configuration. For the global configuration, it’s 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 configuration. This URL will also be used by the Commerce API on the front end to retrieve this configuration. For the global configuration, it’s always /.

queryConfiguration lets you specify which facets, sort criteria, and additional fields you want to be returned for this configuration.

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.

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.

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.

Use the specific listing configuration endpoints

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

Every PLP on your website requires a separate listing configuration. This configuration defines the name and url of the listing page, along with which rules to apply to products returned by the configuration.

Each specific listing configuration must have at least one filter rule, as shown in the following sample:

{
    "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 configuration. This is also what appears in the CMH.

Specify the url associated with the listing configuration. This URL will also be used by the Commerce API on the front end to retrieve this configuration.

queryConfiguration lets you 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.

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.

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.

rules lets you specify the ranking rules, filter rules, or pin rules that 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

You can specify the queryConfiguration and rules in both the global and specific configurations, so 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

You can set rankingRules and filterRules in the global listing configuration, but you can’t set pinRules. You can set all three types of rules in a specific listing configuration.

The rules in global and specific configurations are always merged.

Example

You boost "Blue" products in the global configuration using rankingRules. Next, you create a PLP using filterRules to filter products that belong to the "surfboards" category.

When this PLP is queried, it will return surfboards (because of the filter rule in the specific configuration) and boost blue surfboards (because of the ranking rule in the global configuration).

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 uses the `contains` operator to include products where the `cat_slug` attribute contains `clothing/pants`.
	Specify the action that occurs when the rule is met. Filter rules can either `include` or `exclude` products. In this case, include the products.
	Set the `essential` attribute to `true`. Every listing page configuration must feature at least one `essential` filter rule that defines the products included on 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