Commerce API facet field management

This is for:

Developer

In this article

Retrieve a facet field list
Bulk update facet fields
Bulk create facet field configurations

Use the Coveo Commerce API to batch manage certain aspects of your Coveo organization's facet fields, a function that’s not available through the Coveo Merchandising Hub (CMH) Facet manager.

This functionality is particularly useful when you want to sync the information in your Product Information Management (PIM) system with the information stored in your CMH.

Currently, the following operations are supported:

Retrieve the list of facet fields available for a property.
Bulk update facet fields.
Bulk create configurations for facet fields.

The GET /facet/fields endpoint retrieves the list of facet fields available for a specific property.

Use this list to:

Retrieve facet field IDs.
Identify which facet fields are missing display names.
Get an up-to-date overview of a property's facet fields and their configuration.

Privilege required

To execute this API call, you need the View access level on the Merchandising hub domain.

Step 1: Customize the endpoint

GET <PLATFORM_URL>/rest/organizations/<ORGANIZATION_ID>/commerce/v2/tracking-ids/<TRACKING_ID>/facet/fields?page=<PAGE>&perPage=<PER_PAGE> HTTP/1.1

Endpoint variables

Customize the endpoint template by replacing the following variables:

<PLATFORM_URL>: The base URL of the Coveo Platform instance that hosts your organization. For example: https://platform.cloud.coveo.com.
<ORGANIZATION_ID>: The unique identifier of your Coveo organization. Consult this article to learn how to find your organization’s ID.
<TRACKING_ID>: The tracking ID of the property containing the facet fields you want to retrieve. Consult this article to learn how to find a property’s tracking ID.
<PAGE> (optional): The zero-based index of the results page to return. The default value is 0, which represents the first page.
<PER_PAGE> (optional): The number of results to return per page. The default value is 10.

Response

A successful response returns a 200 OK status code in addition to a list of facet fields for the specified property.

Successful response example

{
  "pagination": {
    "page": 0,
    "perPage": 2,
    "totalItems": 150,
    "totalPages": 75
  },
  "items": [
    {
      "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", 
      "field": "cat_color_swatch",
      "type": "REGULAR",
      "displayNames": [
        {
          "language": "en",
          "value": "Swatch"
        },
        {
          "language": "fr",
          "value": "Échantillon"
        }
      ],
      "sortCriteria": "RELEVANCE",
      "initialNumberOfValues": 3,
      "injectionDepth": 1000,
      "pinnedValues": [
        {
          "language": "en",
          "values": ["Blue"]
        }
      ]
    }
  ]
}

id: This ID will be required for the bulk operations referenced in this article.

Use the PUT /facet/fields/bulk-update endpoint to bulk update facet fields in a specific property. You can use this operation to modify multiple facet fields in a single API call.

This operation can be used to:

Update missing display names.
Modify sort criteria.
Change the initial number of values.
Update and add pinned values.
Update range details.
Update injection depth.

Privilege required

To execute this API call, you need the Edit access level on the Merchandising hub domain.

Step 1: Customize the endpoint

PUT <PLATFORM_URL>/rest/organizations/<ORGANIZATION_ID>/commerce/v2/tracking-ids/<TRACKING_ID>/facet/fields/bulk-update HTTP/1.1

Endpoint variables

Customize the endpoint template by replacing the following variables:

<PLATFORM_URL>: The base URL of the Coveo Platform instance that hosts your organization. For example: https://platform.cloud.coveo.com.
<ORGANIZATION_ID>: The unique identifier of your Coveo organization. Consult this article to learn how to find your organization’s ID.
<TRACKING_ID>: The tracking ID of the property containing the facet fields you want to edit. Consult this article to learn how to find a property’s tracking ID.

Step 2: Create the request body

Build the request body to include the changes you want to apply to eligible facet field configurations.

Required body request properties

Schema identifying properties

The identified properties are required in the request body.

[
  {
    "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", 
    "field": "cat_color_swatch", 
    "type": "REGULAR", 
    "displayNames": [ 
      {
        "language": "en",
        "value": "Type"
      }
    ],
    "sortCriteria": "RELEVANCE",
    "initialNumberOfValues": 10,
    "injectionDepth": 1000,
    "useInFilterSuggestions": false,
    "resultsMustMatch": "AT_LEAST_ONE_VALUE",
    "pinnedValues": [
      {
        "language": "en",
        "values": [
          "Multi Color",
          "Red",
          "Green",
          "Brown",
          "Yellow",
          "Lime",
          "Khaki"
        ]
      }
    ]
  }
]

	`id`: The unique identifier of the facet field to update. You can retrieve this ID by using the Retrieve a facet field list operation.
	`field`: The name of the field associated with the facet field.
	`type`: The type of the facet field. Possible values are `REGULAR`, `HIERARCHICAL`, `CONTINUOUS`, and `NUMERICAL_RANGES`.
	The full configuration of the facet field is required for the request to be successful, not just the properties you want to update. The configurations can be found in the facet field list.

Example

To change the initialNumberOfValues from 10 to 5, you would include the facet's full configuration in the request body:

{
  "id": "ddb5cec6-99d7-4af4-b447-417e9b86c3e5",
  "field": "cat_type",
  "type": "REGULAR",
  "displayNames": [
    {
      "language": "en",
      "value": "Type"
    }
  ],
  "sortCriteria": "RELEVANCE",
  "initialNumberOfValues": 5,
  "injectionDepth": 1000,
  "useInFilterSuggestions": false,
  "resultsMustMatch": "AT_LEAST_ONE_VALUE",
  "pinnedValues": []
}

Editable properties

Sample body template

The identified properties can be edited using this call.

[
  {
    "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1",
    "field": "cat_color_swatch",
    "type": "REGULAR",
    "displayNames": [ 
      {
        "language": "en", 
        "value": "Swatch" 
      }
    ],
    "sortCriteria": "RELEVANCE", 
    "initialNumberOfValues": 3, 
    "injectionDepth": 1000, 
    "pinnedValues": [ 
      {
        "language": "en", 
        "values": [ 
          "Multi Color",
          "Red",
          "Green",
          "Brown",
          "Yellow",
          "Lime",
          "Khaki"
        ]
      }
    ]
  },
  {
    "id": "rget6t3d-6624t-5r85-b5k1-780eed22a8e1",
    "field": "ec_price_manual",
    "type": "NUMERICAL_RANGES",
    "displayNames": [
      {
        "language": "en",
        "value": "Price"
      }
    ],
    "rangeDetails": { 
      "type": "MANUAL", 
      "ranges": [ 
        {
          "start": 0,
          "end": 10
        },
        {
          "start": 10,
          "end": 20
        },
        {
          "start": 20,
          "end": 30
        }
      ]
    }
  }
]

	`displayNames`: An array containing the names displayed for the facet field in all supported languages.
	`language`: The ISO 639 language code for the display name (for example, `en` for English, `fr` for French, `nl` for Dutch). Note that only languages supported by the organization can be added.
	`value`: The display name value in the specified language.
	`sortCriteria`: The criteria used to sort the facet field values. Possible values are `RELEVANCE`, `OCCURRENCES`, `HIERARCHICAL`, and `ALPHANUMERIC`.
	`initialNumberOfValues`: An integer indicating the number of facet field values initially displayed to users.
	`injectionDepth`: Optional. The number of top-ranked results from which to extract facet field values. The default value is `1000`. We recommend leaving this field at the default value to keep query time at a minimum. Increasing the value can be done for broad queries with many results, such as in legal or compliance-sensitive cases, but results in slower query times.
	`pinnedValues`: An array specifying facet field values that should always appear at the top of the list.
	`language`: The ISO 639 language code for the pinned value.
	`values`: An array of values to pin for the specified language.
	`rangeDetails`: (Only for `NUMERICAL_RANGES` type facet fields) An object that defines how ranges are set up.
	Range `type`: Either `MANUAL` or `AUTOMATIC_EVEN`.
	`ranges`: For `MANUAL`, an array of objects with `start` and `end` properties. For `AUTOMATIC_EVEN`, `numberOfRanges` is used to specify the number of ranges to generate automatically.

Note

A successful response returns a 200 OK status code.

Use the PUT /facet/fields/bulk-create endpoint to bulk create facet field configurations in a specific property. You can use this operation to create multiple facet field configurations in a single API call.

This operation can be used to:

Add display names to a facet field.
Synchronize CMH facet field display names with PIM data.
Set sort criteria.
Set the initial number of values.
Set the filter suggestions option.
Set pinned values.
Set range details.
Set injection depth.

This call will only work on fields that are already configured as facet fields.

Privilege required

To execute this API call, you need the Edit access level on the Merchandising hub domain.

Step 1: Customize the endpoint

PUT <PLATFORM_URL>/rest/organizations/<ORGANIZATION_ID>/commerce/v2/tracking-ids/<TRACKING_ID>/facet/fields/bulk-create HTTP/1.1

Endpoint variables

Customize the endpoint template by replacing the following variables:

<PLATFORM_URL>: The base URL of the Coveo Platform instance that hosts your organization. For example: https://platform.cloud.coveo.com.
<ORGANIZATION_ID>: The unique identifier of your Coveo organization. Consult this article to learn how to find your organization’s ID.
<TRACKING_ID>: The tracking ID of the property containing the facet fields you want to edit. Consult this article to learn how to find a property’s tracking ID.

Step 2: Create the request body

Build the request body to include the items you want to add to the facet field configurations.

Required body request properties

Schema identifying properties

The identified properties are required in the request body.

[
  {
    "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", 
    "field": "cat_color_swatch", 
    "type": "REGULAR" 
  }
]

	`id`: The unique identifier of the facet field to update. You can retrieve this ID by using the Retrieve a facet field list operation.
	`field`: The name of the field associated with the facet field.
	`type`: The type of the facet field. Possible values are `REGULAR`, `HIERARCHICAL`, `CONTINUOUS`, and `NUMERICAL_RANGES`.

Configurable additions

Sample body template

The identified properties can be added using this call.

[
  {
    "id": "a164b3cf-9b66-477c-92f3-8b4d16fd3664",
    "field": "cat_fastening",
    "type": "REGULAR",
    "displayNames": [ 
      {
        "language": "nl", 
        "value": "klittenbandsluiting" 
      },
      {
        "language": "en",
        "value": "velcro fastening"
      }
    ],
    "sortCriteria": "RELEVANCE", 
    "initialNumberOfValues": 10, 
    "injectionDepth": 1000, 
    "useInFilterSuggestions": false, 
    "pinnedValues": [ 
      {
        "language": "en", 
        "values": [ 
          "Multi Color",
          "Red",
          "Green",
          "Brown",
          "Yellow",
          "Lime",
          "Khaki"
        ]
      },
      {
        "language": "nl",
        "values": [
          "Meerkleurig",
          "Rood",
          "Groen",
          "Bruin",
          "Geel",
          "Limoen",
          "Khaki"
        ]
      }
    ]
  },
  {
    "id": "b264b3cf-9b66-477c-92f3-8b4d16fd3664",
    "field": "ec_price_manual",
    "type": "NUMERICAL_RANGES",
    "displayNames": [
      {
        "language": "en",
        "value": "Price"
      }
    ],
    "rangeDetails": { 
      "type": "MANUAL", 
      "ranges": [ 
        {
          "start": 0,
          "end": 50
        },
        {
          "start": 50,
          "end": 100
        },
        {
          "start": 100,
          "end": 150
        }
      ]
    }
  }
]

	`displayNames`: An array containing the names displayed for the facet field in all supported languages.
	`language`: The ISO 639 language code for the display name (for example, `en` for English, `fr` for French, `nl` for Dutch). Note that only languages supported by the organization can be added.
	`value`: The display name value in the specified language.
	`sortCriteria`: The criteria used to sort the facet field values. Possible values are `RELEVANCE`, `OCCURRENCES`, `HIERARCHICAL`, and `ALPHANUMERIC`.
	`initialNumberOfValues`: An integer indicating the number of facet field values initially displayed to users.
	`injectionDepth`: Optional. The number of top-ranked results from which to extract facet field values. The default value is `1000`. We recommend leaving this field at the default value to keep query time at a minimum. Increasing the value can be done for broad queries with many results, such as in legal or compliance-sensitive cases, but results in slower query times.
	`useInFilterSuggestions`: A Boolean option indicating whether to use this facet field in filter suggestions.
	`pinnedValues`: An array specifying facet field values that should always appear at the top of the list.
	`language`: The ISO 639 language code for the pinned value.
	`values`: An array of values to pin for the specified language.
	`rangeDetails`: (Only for `NUMERICAL_RANGES` type facet fields) An object that defines how ranges are set up.
	Range `type`: Either `MANUAL` or `AUTOMATIC_EVEN`.
	`ranges`: For `MANUAL`, an array of objects with `start` and `end` properties. For `AUTOMATIC_EVEN`, `numberOfRanges` is used to specify the number of ranges to generate automatically.

Note

A successful response returns a 200 OK status code.