Facet Options

Facet options represent the "values" for Facets. For a Brand facet, these would be Nike, Adidas or Puma.

The facet options API may be used to configure the way facet options are displayed. Using this set of endpoints, you may slot options to specific positions, change their display names, hide them, etc)

Create a facet option config#

To add a new facet option configuration to a facet group, use the POST method.

Create a facet option configuration
curl -X POST \
-H "Content-Type: application/json" \
-d '{"value": "nature_valley", "display_name": "Nature Valley", "position": 1, "data": null, "hidden": false}'
-u "[your token]"
"https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]"
Response
{
"value": "nature_valley",
"display_name": "Nature Valley",
"position": 1,
"data": null,
"hidden": false
}

HTTP request#

POST https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.

JSON Parameters#

AttributeTypeRequired?Description
valuestringYesA value for this facet option. Must be unique for particular facet
display_namestringNoA display name for this facet option. Default value is null
positionintegerNoUsed to order facet options. Default value is null
hiddenbooleanNoSpecifies whether the facet option is hidden from users. Default value is false
datadictNoDictionary with any extra facet option data. Default value is null

Get all option configs for facet#

To get configurations of all facet options for a particular facet group, use the GET method.

Get facet options
curl -X GET \
-H "Content-Type: application/json" \
-u "[your token]"
"https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet options per page]"
Response
{
"facet_options": [
{
"value": "Nature Valley",
"display_name": "nature_valley",
"position": 1,
"data": null,
"hidden": false,
},
{
"value": "McCormick's Organics",
"display_name": "mccormicks-organics",
"position": 2,
"data": null,
"hidden": false,
},
...
],
"total_count": 10,
}

HTTP request#

GET https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]&page=[page number]&num_results_per_page=[number of facet options per page]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.
pageintegerNoPage number you'd like to request. Defaults to 1.
num_results_per_pageintegerNoNumber of facet options per page in paginated response. Default value is 100.

Batch update or create facet options configs#

To update or create multiple facet options, use the PATCH method. If a facet option config with provided value already exists it is updated partially, otherwise it is created.

Batch update or create facets options configs
curl -X PATCH \
-H "Content-Type: application/json" \
-u "[your token]" \
-d '[{"value": "nature_valley", "display_name": "New display name"}, {"display_name": "McCormick Organics", "value": "mccormicks-organics", "position": 2, "hidden": false}]'
"https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]"
Response
[
{
"value": "nature_valley",
"display_name": "New display name",
"position": 1,
"data": null,
"hidden": false
},
{
"value": "mccormicks-organics",
"display_name": "McCormick Organics",
"position": 2,
"data": null,
"hidden": false
}
]

HTTP request#

PATCH https://ac.cnstrc.com/v1/facets/<facet_group_name>/options?key=[your API key]&section=[your section]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.

JSON Parameters#

Batch update endpoint expects a list of item updates. Each item parameters can be any subset of those listed in the Create a facet option configuration section, except that value parameter is required (to identify which facet options config to update).

Get a single facet option config#

To retrieve the configuration of a single facet option, use the GET method.

Get facet option
curl -X GET \
-H "Content-Type: application/json" \
-u "[your token]"
"https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]"
Response
{
"value": "nature_valley",
"display_name": "Nature Valley",
"position": 1,
"data": null,
"hidden": false
}

HTTP request#

GET https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.

Update facet option (total)#

To update the configuration of a facet option completely (replace), use the PUT method.

caution

This will overwrite all other configurations you may have defined for the facet option, resetting them to their defaults.

Replace facet option's configurations
curl -X PUT \
-H "Content-Type: application/json" \
-d '{"value": "nature_valley", "display_name": "Nature Valley", "position": 1, "data": null, "hidden": false}' \
-u "[your token]"
"https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]"
Response
{
"value": "nature_valley",
"display_name": "Nature Valley",
"position": 1,
"data": null,
"hidden": false
}

HTTP request#

PUT https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.

JSON Parameters#

The JSON parameters are the same as those in the Create a facet option configuration section.

Update facet option (partial)#

To update the configuration of a facet option partially (change only some attributes), use the PATCH method.

Modify facet option
curl -X PATCH \
-H "Content-Type: application/json" \
-d '{"display_name": "Nature Valley"}' \
-u "[your token]"
"https://ac.cnstrc.com/v1/facets/<facet_group_name>?key=[your API key]&section=[your section]"
Response
{
"value": "nature_valley",
"display_name": "Nature Valley",
"position": 1,
"data": null,
"hidden": false
}

HTTP request#

PATCH https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.

JSON Parameters#

The JSON parameters can be any subset of those listed in the Create a facet configuration section.

Delete a facet option config#

To delete the configuration of a facet option from the facet, use the DELETE method.

Only do this if you want all configuration options for the facet option to go back to their default values.

Delete a facet option configuration
curl -X DELETE \
-H "Content-Type: application/json" \
-u "[your token]"
"https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]"
Response
{
"value": "nature_valley",
"display_name": "Nature Valley",
"position": 1,
"data": null,
"hidden": false
}

HTTP request#

DELETE https://ac.cnstrc.com/v1/facets/<facet_group_name>/options/<facet_option_value>?key=[your API key]&section=[your section]

URL Parameters#

AttributeTypeRequired?Description
sectionstringNoThe section in which your facet is defined. Typically, this will be Products.