API Reference
Proof Schedule™UI LibrariesClient LibrariesBlogMain Site

Facets

🚧

Important

As of November 2024, facets are no longer specified and ingested via catalog upload. You should treat facets as product metadata. Once uploaded, you can configure facets using the Constructor dashboard or our API.

Facets play a crucial role in creating an intuitive and efficient search experience by helping users quickly find the products they seek by applying relevant filters, such as price, brand, color, etc.

When you configure a facet, you control how the facet options are displayed, sorted, and behave in product listing pages.

Available configurations include:

  • Display name. Customize the name of the facet as it appears to end users.
  • Sort order. Control the order in which facets or facet options appear (for example, alphanumeric, etc.).
  • Type. Specify whether a facet displays as a list of options (multiple), a hierarchical structure, or a range (for numerical values).
  • Range configuration. Specify how ranges are defined and displayed for numerical facets. These ranges can be static (predefined buckets) or dynamic (automatically adjusted based on data).
  • Visibility and access. Specify whether facets are hidden or protected. Hidden facets are not displayed to end users but can be accessed via API. Protected facets require authentication to be accessed.

When uploading a product catalog, treat facets as product metadata. Once uploaded, you can configure facets using the Constructor dashboard or our API. You must configure a facet for it to appear on a product listing page. Facet configurations are not created automatically.

It is possible to configure facet groups and facet options for product data that doesn’t exist in your index. While this ability isn’t supported in the dashboard, you can configure the data using our API.

API endpoints

Facet endpoints

Facet option endpoints

Concepts

Facet configurations are represented with two related concepts: facet groups and facet options. Facet groups represent the facet key and facet options represent the facet value. For example, imagining an item with Brand: Under Armour. The brand would be the facet group (or key), while "Under Armour" would represent the facet option (or value).

The facet options API may be used to configure the way facet options are displayed. Using this set of endpoints, it is possible to slot options to specific positions, change their display names, hide them, and more.

Protected and hidden facets

Product catalogs often include data in the form of facets that shouldn't be displayed to end users. These may contain data that is old, unused, confusing to users or sensitive. Consider a few use cases described below:

Protected facets

A business team wants to incorporate inventory and margins in the ranking formula and in the merchant tools dashboard. However, this is sensitive data. Not only should inventory and margin data be hidden from end users, it also should be prevented from being displayed for search requests without authentication. Declaring this data as a protected (protected: true) can facilitate this.

Hidden facets

A merchant team wants to use an attribute to define merchandizing goals. It should not be shown to end users, but it's not a problem if it could conceivably be accessed from the API. For instance, a "season" property is set on items that is used to define a Collection. The facet can be set to hidden (hidden: true) to facilitate this case.

Setting hidden state as the default

It is possible to set a default behavior that sets all facets to hidden by default upon creation via the API. This involves creating a facet with name=__default__ and setting the property of hidden=true. This configuration ensures that any new facet added to your catalog without a specific setting will automatically be marked as hidden.

🚧

Caution

Before implementing this default hidden state, it's crucial to review your existing facets. This configuration will retrospectively apply to all existing facets that do not have an explicit hidden/non-hidden setting, potentially altering their current visibility to end-users.

Special facets and preserved values

Every facet you create includes a special value: *. This value can be used to filter all items that have the facet. The * value is reserved and cannot be used as a facet option.

Additionally, note that each item in the product catalog will automatically receive an age facet. This facet is configured like any other, except for two fields:

  1. Type: always set to range.
  2. Name: always set to __cnstrc_age.

The age facet value is calculated as the time since __cnstrc_release_time. By default, __cnstrc_release_time is set to the time of item creation in our system. The release time can be used to schedule product launches.

To override the release time and age for a specific item or variation, add the key __cnstrc_release_time with a valid ISO 8601 formatted string or Unix timestamp as the value. Examples of valid formats include 2017-10-08T07:10:12.003+03:00 for ISO 8601 or 1507435812 for Unix timestamps. This key should be added to the item or variation data field.

The key __cnstrc_release_time should be included in the data field, not in the facets field. Items and variations with __cnstrc_release_time in the facets field will be rejected.

Examples

The following examples describe facet configuration requests that can be made via the Create facet configuration endpoint to fulfill different use cases:

Brand facet with alphabetically sorted options and display name configuration for 3 facet options

{
  "name": "brand",
  "display_name": "Brand",
  "sort_order": "value",
  "type": "multiple",
  "data": {},
  "options": [
    {
      "value": "under-armour",
      "display_name": "Under Armour"
    },
    {
      "value": "adidas",
      "display_name": "Adidas"
    },
    {
      "value": "puma",
      "display_name": "Puma"
    }
  ]
}

Price facet configured to be returned as a slider, allowing filtering of products by a price between two values

{
  "name": "price",
  "display_name": "Price",
  "type": "range",
  "range_format": "boundaries"
}

Rating facet with overlapping buckets, for instance if you want to create a rating filter with options

{
  "name": "Rating",
  "type": "range",
  "range_type": "static",
  "range_format": "options",
  "range_inclusive": "above",
  "range_limits": [1, 2, 3, 4]
}