---
title: Use the Query Configurations API
slug: pbbf0247
canonical_url: https://docs.coveo.com/en/pbbf0247/
collection: coveo-for-commerce
source_format: adoc
---
# Use the Query Configurations API
A _query configuration_ is a JSON object that lets you set certain parameters for [queries](https://docs.coveo.com/en/231/) sent from [search interfaces](https://docs.coveo.com/en/2741/) and [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).
Although products can be retrieved from the [index](https://docs.coveo.com/en/204/) without a query configuration, you'll need to [create one](#create-a-query-configuration) to configure the following:

* Sort criteria

* Additional [fields](https://docs.coveo.com/en/200/)

* Number of results per page

* Number of children per result

* Product grouping

> **Note**
>
> If the [Facet manager](https://docs.coveo.com/en/p63f0211/) isn't enabled for your [Coveo organization](https://docs.coveo.com/en/185/), you'll also [use query configurations to set up facets](#use-a-query-configuration-to-manage-facets) for your [search interface](https://docs.coveo.com/en/2741/) or [product listing pages (PLPs)](https://docs.coveo.com/en/m1sf3187/).
> 
> The [Facet manager](https://docs.coveo.com/en/p3oa0420/) 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.

Query configurations can be scoped as [global](#global-query-configurations) or [specific](#specific-query-configurations).
Both let you set the same parameters, but specific query configurations can't be used with all [product discovery solutions](https://docs.coveo.com/en/o9cf0524/):

* The Search [solution](https://docs.coveo.com/en/o9cf0524/) can only use global configurations.

* The Product listings [solution](https://docs.coveo.com/en/o9cf0524/) can use both global and specific configurations.

The parameters in a global query configuration are the default that applies to all [queries](https://docs.coveo.com/en/231/), while those in a specific query configuration only apply to a single PLP.

If there's a conflict between a global and specific configuration, then the parameters in the specific configuration take precedence.

## Create a query configuration

To create a query configuration, make the following request to the [Query Configurations API](https://docs.coveo.com/en/103/api-reference/commerce-api#tag/Query-Configurations):

```http
POST https://platform.cloud.coveo.com/rest/organizations/<ORGANIZATION_ID>/commerce/v2/configurations/query HTTP/1.1
​
Accept: application/json
Content-Type: application/json
Authorization: Bearer **********-****-****-****-************
```

where `<ORGANIZATION_ID>` is the unique identifier of your [Coveo organization](https://docs.coveo.com/en/185/).
To learn how to find your organization ID, see [Find your organization ID](https://docs.coveo.com/en/n1ce5273/).

The following is the basic payload to create a query configuration.
More complete examples are included in the other sections of this article.

```json
{
  "trackingId":  "<TRACKING_ID>", <1>
  "solutionType": "<SOLUTION_TYPE>", <2>
  "targets": [], <3>
  "isGlobal": <SCOPE>, <4>
  "configurationModel": {
    "additionalFields": [],
    "facets": { <5>
      "facets": []
    },
    "perPage": <NUMBER_OF_RESULTS>,
    "sorts": [],
    "numberOfChildren": <NUMBER_OF_CHILDREN>, <6>
    "grouping": {
      "type": "<GROUPING>" <7>
    }
  }
}
```

<1> [`trackingId`](https://docs.coveo.com/en/n8tg0567/) lets you segregate your query 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/) to retrieve the configuration.

<2> `solutionType` is the [product discovery solution](https://docs.coveo.com/en/o9cf0524/) to which this query configuration applies.
This can be either `search` or `listing`.

<3> `targets` lets you specify the name of a single [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/) to which this query configuration applies.
This parameter is only used in [specific query configurations](#specific-query-configurations) for PLPs.
In a global query configuration, omit this parameter.

<4> `isGlobal` defines the scope of the query configuration.
This is `true` for a global configuration and `false` for a specific one.

<5> Only use the `facets` parameter 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/p63f0211/) instead.

<6> `numberOfChildren` sets the maximum number of child [items](https://docs.coveo.com/en/210/) to include in a folded [query](https://docs.coveo.com/en/231/) result.

<7> If the [query pipeline](https://docs.coveo.com/en/180/) that routes [queries](https://docs.coveo.com/en/231/) for this [tracking ID](https://docs.coveo.com/en/o8rb0139/) and [solution](https://docs.coveo.com/en/o9cf0524/) is [configured for product grouping](https://docs.coveo.com/en/l78i2152/), set the `grouping` type to `query_pipeline`.
Otherwise, set it to `none`.
Pin rules will respect this setting.

The resulting query configuration will apply to [queries](https://docs.coveo.com/en/231/) that meet all of the following criteria:

* They include the defined [tracking ID](https://docs.coveo.com/en/o8rb0139/).

* They originate from an interface of the defined [solution](https://docs.coveo.com/en/o9cf0524/) type.

* If the query configuration isn't global, they originate specifically from the [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/) defined in `targets`.

## Global query configurations

Global query configurations define certain common elements that you want returned with each [query](https://docs.coveo.com/en/231/).

You don't have to create a global query configuration before you can query products from a [search interface](https://docs.coveo.com/en/2741/) or [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/).
However, you'll need one to specify the sort criteria, additional [fields](https://docs.coveo.com/en/200/), and a few other parameters that apply when your front end [queries](https://docs.coveo.com/en/231/) the Commerce API.

### Sample global configuration for search

The following global query configuration for the Search solution retrieves the `collection` and `color` [fields](https://docs.coveo.com/en/200/), returns 10 results per page, and sorts by relevance:

```json
{
  "trackingId":  "barca_sports_ca",
  "solutionType": "search", <1>
  "isGlobal": true, <2>
  "configurationModel": { <3>
    "additionalFields": [
      "collection",
      "color"
    ],
    "perPage": 10,
    "sorts": [
      {
        "sortCriteria": "relevance"
      }
    ],
    "numberOfChildren": 0,
    "grouping": {
      "type": "none"
    }
  }
}
```

<1> For the Search [product discovery solution](https://docs.coveo.com/en/o9cf0524/), set `solutionType` to `search`.

<2> In a global query configuration, set `isGlobal` to `true`.

<3> `configurationModel` lets you specify the following parameters: `additionalFields`, `perPage`, `sorts`, `numberOfChildren`, and `grouping`.

You can also configure `facets`, but only 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.
For an example with the `facets` parameter, see [Use a query configuration to manage facets](#use-a-query-configuration-to-manage-facets).

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

### Sample global configuration for listings

The following global query configuration for the Product listings solution retrieves the `collection` and `color` [fields](https://docs.coveo.com/en/200/), returns 20 results per page, and sorts by relevance:

```json
{
  "trackingId":  "barca_sports_ca",
  "solutionType": "listing", <1>
  "isGlobal": true, <2>
  "configurationModel": { <3>
    "additionalFields": [
      "collection",
      "color"
    ],
    "perPage": 20,
    "sorts": [
      {
        "sortCriteria": "relevance"
      }
    ],
    "numberOfChildren": 0,
    "grouping": {
      "type": "none"
    }
  }
}
```

<1> For the Product listings [product discovery solution](https://docs.coveo.com/en/o9cf0524/), set `solutionType` to `listing`.

<2> In a global query configuration, set `isGlobal` to `true`.

<3> `configurationModel` lets you specify the following parameters: `additionalFields`, `perPage`, `sorts`, `numberOfChildren`, and `grouping`.

You can also configure `facets`, but only 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.
For an example with the `facets` parameter, see [Use a query configuration to manage facets](#use-a-query-configuration-to-manage-facets).

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

## Specific query configurations

Specific query configurations define certain common elements that you want returned with each [query](https://docs.coveo.com/en/231/) on a particular [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/).
They let you customize these elements if you want certain PLPs to behave differently from the default parameters defined in the global query configuration.

For example, the default behaviour for your PLPs might be to sort by relevance, but you want to sort by price on the "Promotions" PLP.

The following specific query configuration targets the `Accessories|Bags` [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/).
It retrieves the `color` and `size` [fields](https://docs.coveo.com/en/200/), returns 20 results per page, and sorts by price (based on the `ec_price` [field](https://docs.coveo.com/en/200/)) in ascending order:

```json
{
  "trackingId":  "barca_sports_ca",
  "solutionType": "listing", <1>
  "targets": [ <2>
    "Accessories|Bags"
  ],
  "isGlobal": false, <3>
  "configurationModel": { <4>
    "additionalFields": [
      "color",
      "size"
    ],
    "perPage": 20,
    "sorts": [
      {
        "sortCriteria": "fields",
        "fields": [
          {
            "field": "ec_price",
            "direction": "asc",
            "displayNames": [
              {
                "value": "Price",
                "language": "en"
              },
              {
                "value": "Prix",
                "language": "fr"
              }
            ]
          }
        ]
      }
    ],
    "numberOfChildren": 0,
    "grouping": {
      "type": "none"
    }
  }
}
```

<1> For the Product listings [product discovery solution](https://docs.coveo.com/en/o9cf0524/), set `solutionType` to `listing`.

<2> The name of the specific [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/) to which this query configuration applies.
Each specific configuration can only apply to one PLP, so the `targets` array can only hold a single value.

<3> In a specific query configuration, set `isGlobal` to `false`.

<4> `configurationModel` lets you specify the following parameters: `additionalFields`, `perPage`, `sorts`, `numberOfChildren`, and `grouping`.

You can also configure `facets`, but only 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.
For an example with the `facets` parameter, see [Use a query configuration to manage facets](#use-a-query-configuration-to-manage-facets).

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

## Use a query configuration to manage facets

You should use the [Facet manager](https://docs.coveo.com/en/p5da0252/) in the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) to configure [facets](https://docs.coveo.com/en/198/) for your [search interface](https://docs.coveo.com/en/2741/) or [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/).

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

However, you can use a query configuration to set up your [facets](https://docs.coveo.com/en/198/) if the [Facet manager](https://docs.coveo.com/en/p63f0211/) isn't enabled for your [Coveo organization](https://docs.coveo.com/en/185/).

The following specific query configuration targets the `Canoes & Kayaks` [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/).
It retrieves the `color` and `storage` [fields](https://docs.coveo.com/en/200/), configures several [facets](https://docs.coveo.com/en/198/), returns 20 results per page, and sorts by price (based on the `ec_price` [field](https://docs.coveo.com/en/200/)) in ascending order:

```json
{
  "trackingId":  "barca_sports_ca",
  "solutionType": "listing", <1>
  "targets": [ <2>
    "Canoes & Kayaks"
  ],
  "isGlobal": false, <3>
  "configurationModel": { <4>
    "additionalFields": [
      "color",
      "storage"
    ],
    "facets": {
      "enableIndexFacetOrdering": true,
      "freezeFacetOrder": true,
      "facets": [
        {
          "facetId": "year",
          "field": "year",
          "displayNames": [
            {
              "value": "Year",
              "language": "en"
            },
            {
              "value": "Année",
              "language": "fr"
            }
          ],
          "values": [
            {
              "state": "idle",
              "preventAutoSelect": false,
              "start": "2023/10/01@00:00:00",
              "end": "2023/10/31@23:59:59",
              "endInclusive": true
            },
            {
              "state": "idle",
              "preventAutoSelect": true,
              "start": "2023/11/01@00:00:00",
              "end": "2023/11/30@23:59:59",
              "endInclusive": false
            },
            {
              "state": "selected",
              "preventAutoSelect": true,
              "start": "2023/12/01@00:00:00",
              "end": "2023/12/31@23:59:59",
              "endInclusive": true
            }
          ],
          "numberOfValues": 3,
          "preventAutoSelect": false,
          "sortCriteria": "score",
          "isFieldExpanded": true,
          "type": "dateRange",
          "generateAutomaticRanges": true
        },
        {
          "facetId": "ec_category",
          "field": "ec_category",
          "displayNames": [
            {
              "value": "Category",
              "language": "en"
            },
            {
              "value": "Catégorie",
              "language": "fr"
            }
          ],
          "values": [
            {
              "state": "selected",
              "preventAutoSelect": true,
              "value": "Canoes & Kayaks",
              "children": [
                {
                  "state": "selected",
                  "preventAutoSelect": true,
                  "value": "Kayaks",
                  "children": [
                    {
                      "state": "selected",
                      "preventAutoSelect": true,
                      "value": "Folding Kayaks"
                    }
                  ]
                },
                {
                  "state": "idle",
                  "preventAutoSelect": true,
                  "value": "Sea Kayaks"
                }
              ]
            },
            {
              "state": "selected",
              "preventAutoSelect": false,
              "value": "Canoes"
            }
          ],
          "numberOfValues": 5,
          "preventAutoSelect": true,
          "sortCriteria": "score",
          "isFieldExpanded": true,
          "type": "hierarchical",
          "delimitingCharacter": "|",
          "basePaths": {
            "value": [
              "Boats"
            ],
            "language": "en"
          },
          "filterByBasePath": true
        },
        {
          "facetId": "ec_brand",
          "field": "ec_brand",
          "displayNames": [
            {
              "value": "string",
              "language": "en"
            }
          ],
          "values": [
            {
              "state": "idle",
              "value": "string"
            }
          ],
          "numberOfValues": 0,
          "type": "regular",
          "latitude": "@latitude",
          "longitude": "@longitude"
        },
        {
          "facetId": "ec_price",
          "field": "ec_price",
          "displayNames": [
            {
              "value": "Price",
              "language": "en"
            },
            {
              "value": "Prix",
              "language": "fr"
            }
          ],
          "values": [
            {
              "state": "idle",
              "preventAutoSelect": true,
              "start": "0",
              "end": "999",
              "endInclusive": "true"
            },
            {
              "state": "selected",
              "preventAutoSelect": true,
              "start": "1000",
              "end": "2000",
              "endInclusive": "false"
            },
            {
              "state": "selected",
              "preventAutoSelect": true,
              "start": "2001",
              "end": "3000",
              "endInclusive": "false"
            }
          ],
          "numberOfValues": 3,
          "preventAutoSelect": true,
          "sortCriteria": "score",
          "isFieldExpanded": true,
          "type": "numericalRange",
          "generateAutomaticRanges": true,
          "rangeAlgorithm": "equiprobable"
        },
        {
          "facetId": "ec_brand",
          "field": "ec_brand",
          "displayNames": [
            {
              "value": "Brand",
              "language": "en"
            },
            {
              "value": "Marque",
              "language": "fr"
            }
          ],
          "values": [
            {
              "state": "selected",
              "preventAutoSelect": false,
              "value": "Aqua Sports"
            },
            {
              "state": "idle",
              "preventAutoSelect": false,
              "value": "Aqua Marina"
            },
            {
              "state": "idle",
              "preventAutoSelect": false,
              "value": "HO Sports"
            }
          ],
          "numberOfValues": 3,
          "preventAutoSelect": false,
          "sortCriteria": "score",
          "isFieldExpanded": true,
          "type": "regular",
          "customOrder": [
            "string"
          ]
        }
      ]
    },
    "perPage": 20,
    "sorts": [
      {
        "sortCriteria": "fields",
        "fields": [
          {
            "field": "ec_price",
            "direction": "asc",
            "displayNames": [
              {
                "value": "Price",
                "language": "en"
              },
              {
                "value": "Prix",
                "language": "fr"
              }
            ]
          }
        ]
      }
    ],
    "numberOfChildren": 0,
    "grouping": {
      "type": "none"
    }
  }
}
```

<1> For the Product listings [product discovery solution](https://docs.coveo.com/en/o9cf0524/), set `solutionType` to `listing`.

<2> The name of the specific [product listing page (PLP)](https://docs.coveo.com/en/m1sf3187/) to which this query configuration applies.
Each specific configuration can only apply to one PLP, so the `targets` array can only hold a single value.

<3> In a specific query configuration, set `isGlobal` to `false`.

<4> `configurationModel` lets you specify the following parameters: `additionalFields`, `facets`, `perPage`, `sorts`, `numberOfChildren`, and `grouping`.