--- title: Commerce API facet field management slug: pb5d0258 canonical_url: https://docs.coveo.com/en/pb5d0258/ collection: coveo-for-commerce source_format: adoc --- # Commerce API facet field management Use the [Coveo Commerce API](https://docs.coveo.com/en/103#tag/Facet-Field-Configurations) to batch manage certain aspects of your [Coveo organization](https://docs.coveo.com/en/185/)'s [facet fields](https://docs.coveo.com/en/p9pn0467/), a function that's not available through the [Coveo Merchandising Hub (CMH)](https://docs.coveo.com/en/o5290573/) [Facet manager](https://docs.coveo.com/en/p3oa0420/). This functionality is particularly useful when you want to synchronize the information in your Product Information Management (PIM) system with the information stored in your [CMH](https://docs.coveo.com/en/o5290573/). Currently, the following operations are supported: * [Retrieve the list of facet fields available for a property](#retrieve-a-facet-field-list). * [Bulk update facet fields](#bulk-update-facet-fields). * [Bulk create configurations for facet fields](#bulk-create-facet-field-configurations). ## Retrieve a facet field list The **GET /facet/fields** endpoint retrieves the list of [facet fields](https://docs.coveo.com/en/p9pn0467/) available for a specific property. Use this list to: * Retrieve [facet field](https://docs.coveo.com/en/p9pn0467/) IDs. * Identify which [facet fields](https://docs.coveo.com/en/p9pn0467/) are missing display names. * Get an up-to-date overview of a [property](https://docs.coveo.com/en/p4ue0547/)'s [facet fields](https://docs.coveo.com/en/p9pn0467/) and their configuration. ### Privilege required To execute this API call, you need the **View** [access level](https://docs.coveo.com/en/2818/) on the [Merchandising hub domain](https://docs.coveo.com/en/1707#merchandising-hub-domain). ### Step 1: Customize the endpoint ```http GET /rest/organizations//commerce/v2/tracking-ids//facet/fields?page=&perPage= HTTP/1.1 ``` #### Endpoint variables Customize the endpoint template by replacing the following variables: * ``: The base URL of the Coveo Platform instance that hosts your organization. For example: `https://platform.cloud.coveo.com`. * ``: The unique identifier of your Coveo organization. Consult this article to learn how to find [your organization's ID](https://docs.coveo.com/en/n1ce5273/). * ``: The {tracking-ID} of the property containing the [facet fields](https://docs.coveo.com/en/p9pn0467/) you want to retrieve. Consult this article to learn how to find [a property's tracking ID](https://docs.coveo.com/en/o7vh0012/). * `` (optional): The zero-based [index](https://docs.coveo.com/en/204/) of the results page to return. The default value is `0`, which represents the first 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](https://docs.coveo.com/en/p9pn0467/) for the specified property. **Successful response example** ```json { "pagination": { "page": 0, "perPage": 2, "totalItems": 150, "totalPages": 75 }, "items": [ { "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", <1> "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"] } ] } ] } ``` <1> `id`: This ID will be required for the bulk operations referenced in this article. ## Bulk update facet fields Use the **PUT /facet/fields/bulk-update** endpoint to bulk update [facet fields](https://docs.coveo.com/en/p9pn0467/) in a specific property. You can use this operation to modify multiple [facet fields](https://docs.coveo.com/en/p9pn0467/) 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](https://docs.coveo.com/en/2818/) on the [Merchandising hub domain](https://docs.coveo.com/en/1707#merchandising-hub-domain). ### Step 1: Customize the endpoint ```http PUT /rest/organizations//commerce/v2/tracking-ids//facet/fields/bulk-update HTTP/1.1 ``` #### Endpoint variables Customize the endpoint template by replacing the following variables: * ``: The base URL of the [Coveo Platform](https://docs.coveo.com/en/186/) instance that hosts your organization. For example: `https://platform.cloud.coveo.com`. * ``: The unique identifier of your Coveo organization. Consult this article to learn how to [find your organization's ID](https://docs.coveo.com/en/n1ce5273/). * ``: The {tracking-ID} of the property containing the [facet fields](https://docs.coveo.com/en/p9pn0467/) you want to edit. Consult this article to learn how to [find a property's tracking ID](https://docs.coveo.com/en/o7vh0012/). ### Step 2: Create the request body Build the request body to include the changes you want to apply to eligible [facet field](https://docs.coveo.com/en/p9pn0467/) configurations. #### Required body request properties **Schema identifying properties** The identified properties are required in the request [body](https://docs.coveo.com/en/3313/). ```json [ { "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", <1> "field": "cat_color_swatch", <2> "type": "REGULAR", <3> "displayNames": [ <4> { "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" ] } ] } ] ``` <1> `id`: The unique identifier of the {facet-field} to update. You can retrieve this ID by using the [Retrieve a facet field list](#retrieve-a-facet-field-list) operation. <2> `field`: The name of the field associated with the {facet-field}. <3> `type`: The type of the {facet-field}. Possible values are `REGULAR`, `HIERARCHICAL`, `CONTINUOUS`, and `NUMERICAL_RANGES`. <4> 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](#retrieve-a-facet-field-list). > **Example** > > To change the `initialNumberOfValues` from 10 to 5, you would include the [facet](https://docs.coveo.com/en/198/)'s full configuration in the request [body](https://docs.coveo.com/en/3313/): > > ```json { "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. ```json [ { "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", "field": "cat_color_swatch", "type": "REGULAR", "displayNames": [ <1> { "language": "en", <2> "value": "Swatch" <3> } ], "sortCriteria": "RELEVANCE", <4> "initialNumberOfValues": 3, <5> "injectionDepth": 1000, <6> "pinnedValues": [ <7> { "language": "en", <8> "values": [ <9> "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": { <10> "type": "MANUAL", <11> "ranges": [ <12> { "start": 0, "end": 10 }, { "start": 10, "end": 20 }, { "start": 20, "end": 30 } ] } } ] ``` <1> `displayNames`: An array containing the names displayed for the {facet-field} in all supported languages. <2> `language`: The [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes/) 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. <3> `value`: The display name value in the specified language. <4> `sortCriteria`: The criteria used to sort the {facet-field} values. Possible values are `RELEVANCE`, `OCCURRENCES`, `HIERARCHICAL`, and `ALPHANUMERIC`. <5> `initialNumberOfValues`: An integer indicating the number of {facet-field} values initially displayed to users. <6> `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. <7> `pinnedValues`: An array specifying {facet-field} values that should always appear at the top of the list. <8> `language`: The [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes/) for the pinned value. <9> `values`: An array of values to pin for the specified language. <10> `rangeDetails`: (Only for `NUMERICAL_RANGES` type {facet-fields}) An object that defines how ranges are set up. <11> Range `type`: Either `MANUAL` or `AUTOMATIC_EVEN`. <12> `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. ## Bulk create facet field configurations Use the **PUT /facet/fields/bulk-create** endpoint to bulk create [facet field](https://docs.coveo.com/en/p9pn0467/) configurations in a specific property. You can use this operation to create multiple [facet field](https://docs.coveo.com/en/p9pn0467/) configurations in a single API call. This operation can be used to: * Add display names to a [facet field](https://docs.coveo.com/en/p9pn0467/). * Synchronize CMH [facet field](https://docs.coveo.com/en/p9pn0467/) 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. > **Important** > > This call will only work on fields that are already configured as [facet fields](https://docs.coveo.com/en/p9pn0467/). ### Privilege required To execute this API call, you need the **Edit** [access level](https://docs.coveo.com/en/2818/) on the [Merchandising hub domain](https://docs.coveo.com/en/1707#merchandising-hub-domain). ### Step 1: Customize the endpoint ```http PUT /rest/organizations//commerce/v2/tracking-ids//facet/fields/bulk-create HTTP/1.1 ``` #### Endpoint variables Customize the endpoint template by replacing the following variables: * ``: The base URL of the Coveo Platform instance that hosts your organization. For example: `https://platform.cloud.coveo.com`. * ``: The unique identifier of your Coveo organization. Consult this article to learn how to [find your organization's ID](https://docs.coveo.com/en/n1ce5273/). * ``: The {tracking-ID} of the property containing the [facet fields](https://docs.coveo.com/en/p9pn0467/) you want to edit. Consult this article to learn how to [find a property's tracking ID](https://docs.coveo.com/en/o7vh0012/). ### 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](https://docs.coveo.com/en/3313/). ```json [ { "id": "dc184eb9-452c-4a42-b8b8-780eed22a8e1", <1> "field": "cat_color_swatch", <2> "type": "REGULAR" <3> } ] ``` <1> `id`: The unique identifier of the {facet-field} to update. You can retrieve this ID by using the [Retrieve a facet field list](#retrieve-a-facet-field-list) operation. <2> `field`: The name of the field associated with the {facet-field}. <3> `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. ```json [ { "id": "a164b3cf-9b66-477c-92f3-8b4d16fd3664", "field": "cat_fastening", "type": "REGULAR", "displayNames": [ <1> { "language": "nl", <2> "value": "klittenbandsluiting" <3> }, { "language": "en", "value": "velcro fastening" } ], "sortCriteria": "RELEVANCE", <4> "initialNumberOfValues": 10, <5> "injectionDepth": 1000, <6> "useInFilterSuggestions": false, <7> "pinnedValues": [ <8> { "language": "en", <9> "values": [ <10> "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": { <11> "type": "MANUAL", <12> "ranges": [ <13> { "start": 0, "end": 50 }, { "start": 50, "end": 100 }, { "start": 100, "end": 150 } ] } } ] ``` <1> `displayNames`: An array containing the names displayed for the {facet-field} in all supported languages. <2> `language`: The [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes/) 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. <3> `value`: The display name value in the specified language. <4> `sortCriteria`: The criteria used to sort the {facet-field} values. Possible values are `RELEVANCE`, `OCCURRENCES`, `HIERARCHICAL`, and `ALPHANUMERIC`. <5> `initialNumberOfValues`: An integer indicating the number of {facet-field} values initially displayed to users. <6> `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. <7> `useInFilterSuggestions`: A Boolean option indicating whether to use this {facet-field} in filter suggestions. <8> `pinnedValues`: An array specifying {facet-field} values that should always appear at the top of the list. <9> `language`: The [ISO 639 language code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes/) for the pinned value. <10> `values`: An array of values to pin for the specified language. <11> `rangeDetails`: (Only for `NUMERICAL_RANGES` type {facet-fields}) An object that defines how ranges are set up. <12> Range `type`: Either `MANUAL` or `AUTOMATIC_EVEN`. <13> `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.