---
title: Create listing configurations (legacy)
slug: o78c0306
canonical_url: https://docs.coveo.com/en/o78c0306/
collection: coveo-for-commerce
source_format: adoc
---
# Create listing configurations (legacy)

> **Important**
>
> This article covers the legacy Listing Configurations API.
> The [Coveo Platform](https://docs.coveo.com/en/186/) no longer uses listing configurations to configure [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/) or define rules.
> 
> This functionality has been replaced as follows:
> 
> * Listing pages are [created](https://docs.coveo.com/en/pbjb9139/) individually using the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) or in a batch using the Public Listing Page API.
> 
> * Query configurations are managed through the dedicated [Query Configurations API](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Query-Configurations).
> 
> * Rules are managed in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/).
> 
> 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)](https://docs.coveo.com/en/m1sf3187/).

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](https://docs.coveo.com/en/198/), sorting, and additional [fields](https://docs.coveo.com/en/200/).

* **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](#use-the-specific-listing-configuration-endpoints) 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](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Listing-Configurations) and providing a configuration JSON.

If all your listing pages share configuration details, such as common [facets](https://docs.coveo.com/en/198/) 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:

```json
{
    "name": "GLOBAL", <1>
    "trackingId": "<TRACKING_ID>", <2>
    "patterns": [ <3>
        {
            "url": "/"
        }
    ],
    "queryConfiguration": { <4>
        "additionalFields": [
            "color",
            "size"
        ],
        "facets": { <5>
            "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": { <6>
        "rankingRules": [],
        "filterRules": [],
        "pinRules": []
    },
    "scope": "global" <7>
}
```

<1> The `name` of the listing configuration.
For the global configuration, it's always `GLOBAL`.

<2> The [`trackingId`](https://docs.coveo.com/en/n8tg0567/) 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](https://docs.coveo.com/en/o8rb0139/).

<3> 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 `/`.

<4> `queryConfiguration` lets you specify which [facets](https://docs.coveo.com/en/198/), sort criteria, and additional [fields](https://docs.coveo.com/en/200/) you want to be returned for this configuration.

<5> Only use the `facets` property if you're managing [facets](https://docs.coveo.com/en/198/) directly via the Commerce API.
If you're using the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/), use the [Facet manager](https://docs.coveo.com/en/p5da0252/) instead.

> **Important**
>
> The [Facet manager](https://docs.coveo.com/en/p63f0211/) in the CMH is currently in open beta.
> If you gained access to the CMH before the [Facet manager](https://docs.coveo.com/en/p63f0211/) was available and would like to adopt it, contact your Coveo representative.

<6> `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](#using-rule-operators).

<7> 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](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Listing-Configurations) 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:

```json
{
    "name": "<NAME>", <1>
    "trackingId": "<TRACKING_ID>",
    "patterns": [ <2>
        {
            "url": "https://sports.barca.group/browse/surfboards"
        }
    ],
    "queryConfiguration": {}, <3>
    "rules": { <4>
        "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"
}
```

<1> The `name` of the listing configuration.
This is also what appears in the CMH.

<2> 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.

<3> `queryConfiguration` lets you specify which [facets](https://docs.coveo.com/en/198/), sort criteria, and additional [fields](https://docs.coveo.com/en/200/) 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](https://docs.coveo.com/en/198/) directly via the Commerce API.
If you're using the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/), use the [Facet manager](https://docs.coveo.com/en/p5da0252/) instead.

> **Important**
>
> The [Facet manager](https://docs.coveo.com/en/p63f0211/) in the CMH is currently in open beta.
> If you gained access to the CMH before the [Facet manager](https://docs.coveo.com/en/p63f0211/) was available and would like to adopt it, contact your Coveo representative.

<4> `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](#using-rule-operators).

For more details on all the possible parameters, see the [reference documentation](https://docs.coveo.com/en/103#tag/Listing-Configurations/operation/create_3).

## 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](https://docs.coveo.com/en/198/) on `ec_price` in the global configuration and then a numeric [facet](https://docs.coveo.com/en/198/) on `rating` in a specific configuration for the "surfboards" [query](https://docs.coveo.com/en/231/).
The Commerce API returns the `rating` [facet](https://docs.coveo.com/en/198/) and not the `ec_price` [facet](https://docs.coveo.com/en/198/) when the user [queries](https://docs.coveo.com/en/231/) 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](https://docs.coveo.com/en/o2gc0008/) 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:

```json
{
  "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": [ <1>
      {
        "filters": [ <2>
          {
            "fieldName": "cat_slug",
            "operator": "contains",
            "value": {
              "type": "array",
              "values": [
                "clothing/pants"
              ]
            }
          }
        ],
        "action": "include", <3>
        "essential": true, <4>
        "name": "Include products where cat_slug contains clothing/pants"
      }
    ],
    "rankingRules": [ <5>
      {
        "filters": [
          {
            "fieldName": "color",
            "operator": "isExactly",
            "value": {
              "type": "array",
              "values": [
                "blue"
              ]
            }
          }
        ],
        "value": 200,
        "action": "boost", <6>
        "name": "Boost blue products"
      }
    ],
    "pinRules": []
  },
  "scope": "specific"
}
```

<1> Create a `filterRules` object to specify the necessary inclusion rule for constructing a PLP.

<2> Define a `filters` object that uses the [`contains`](https://docs.coveo.com/en/o2gc0008#contains) operator to include products where the `cat_slug` attribute contains `clothing/pants`.

<3> Specify the action that occurs when the rule is met.
Filter rules can either `include` or `exclude` products.

In this case, include the products.

<4> 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.

<5> Introduce a `rankingRules` object that uses the [`isExactly`](https://docs.coveo.com/en/o2gc0008#is) operator to boost products with the color `blue`.

<6> 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:

[%header,cols="2"]
|===
|Operator
|Commerce API syntax

|[Is](https://docs.coveo.com/en/o2gc0008#is)
|`isExactly`

|[Is not](https://docs.coveo.com/en/o2gc0008#is-not)
|`isExactlyNot`

|[Contains](https://docs.coveo.com/en/o2gc0008#contains)
|`contains`

|[Does not contain](https://docs.coveo.com/en/o2gc0008#does-not-contain)
|`doesNotContain`

|[Is defined](https://docs.coveo.com/en/o2gc0008#is-defined)
|`isDefined`

|[Is not defined](https://docs.coveo.com/en/o2gc0008#is-not-defined)
|`isNotDefined`

|[Is greater than (>)](https://docs.coveo.com/en/o2gc0008#is-greater-than)[.footnote]^1^
|`isGreaterThan`

|[Is less than (<)](https://docs.coveo.com/en/o2gc0008#is-less-than)[.footnote]^1^
|`isLessThan`

|[Is greater than or equal to (≥)](https://docs.coveo.com/en/o2gc0008#is-greater-than-or-equal-to)[.footnote]^1^
|`isGreaterThanOrEqualTo`

|[Is less than or equal to (≤)](https://docs.coveo.com/en/o2gc0008#is-less-than-or-equal-to)[.footnote]^1^
|`isLessThanOrEqualTo`
|===

--
1. Numeric operators are meant to be used with numerical product attributes such as price, stock, and ratings.
--