Create listing configurations
Create listing configurations
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:
-
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. |
|
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 |
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.
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.
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.