Faceted navigation

Faceted navigation, also known as faceted search, is a type of navigation that allows users to refine product search results by applying filters based on specific product attributes defined by the business, such as color or size. This feature enhances the user experience by providing intuitive filtering options that match how users naturally think about product characteristics.

Configuration

In OrderCloud, facets must be derived from extended properties (XP). However, not all extended properties need to be facets. You can designate an extended property as a facet by creating a Product Facet. For example, creating the following product facet will instruct OrderCloud to index all products with xp.Facets.Color as a facet.

{
  "ID": "color",
  "Name": "Color",
  "XpPath": "Facets.Color",
  "ListOrder": 0,
  "MinCount": 1,
  "xp": {}
}

Properties:

Response format

Once configured, making API calls to either /me/products or /products will return a Meta.Facets object which will be populated with facets relevant to the currently applied filters. By default, facet values will be sorted by count (highest first).

{
  "Meta": {
    "Facets": [
      {
        "Name": "Color",
        "XpPath": "Facets.Color",
        "Values": [
          {
            "Value": "red",
            "Count": 3
          },
          {
            "Value": "purple",
            "Count": 1
          }
        ]
      }
    ]
  }
}

Filter application

Facet filters function similarly to regular filters. You can apply them based on the facet values selected by the user.

For example, if a user selects the "purple" facet, the query would look like this: /me/products?xp.Facets.Color=purple

Value counting

Each facet value will show a count which represents the number of results that would be returned if that filter were applied to your current result set.

The counts are based on the following conventional assumptions:

1. When values of different facets are selected, those filters will be AND'd together, usually resulting in a smaller result set.
2. When different values of the same facet are selected, those filters will be OR'd together, usually resulting in a larger result set.

These assumptions lead to three implications:

1. Facet counts consider all current filters except those on the same facet. For example, if you filter shirts by color=red, the size counts will only show red shirts in each size. Counts for other colors remain unchanged.
2. Counts don't always reflect the exact size of the new result set. For example, assume a result set includes 20 red shirts and 15 blue shirts. Selecting red (20) returns 20 results. Adding blue (15) gives 35 results. This behavior is intuitive for users.
3. In order for counts to be reflected accurately, your filtering logic should match the conventions above.

Multiple values per facet

Single value example:

{
  "ID": "tennis-shoes",
  "Name": "Tennis shoes",
  "Xp": {
    "Color": "red"
  }
}

Multiple values example:

{
  "ID": "tennis-shoes",
  "Name": "Tennis shoes",
  "Xp": {
    "Color": [
      "red",
      "white"
    ]
  }
}

Ensure that all products use either the array format or the primitive format for a single property consistently. Mixing formats can cause indexing issues due to type mismatches.

Price facets

Faceting on price is a common requirement. In OrderCloud, a single product can have multiple prices, leading to a near-limitless combination of pricing configurations. Due to performance implications, faceting on individualized prices is not supported.

Instead, we recommend setting a common retail price on XP. For B2B use cases, it's important to clarify to users that the faceted price represents a "retail" or "MSRP" price, which may differ from their actual negotiated price.

Price is intentionally stored as a string to accommodate for a limitation related to how floating point decimals are indexed.

Example:

{
  "ID": "tennis-shoes",
  "Name": "Tennis shoes",
  "Xp": {
    "Price": "12.99"
  }
}

Best practices

Be selective with facets – Not every extended property should be facetable. Consider that facets are user-facing elements. Some properties may not be appropriate to expose to end users or may not provide meaningful options. For example, you may store routing codes on the product as xp.RoutingCodes=[123,456,789]. These codes may be important for ensuring efficient and accurate movement through the supply chain, but are generally not relevant to end users for product selection or filtering purposes.

XP best practices apply – All of the best practices related to XP apply here since facets are built on top of XP. In particular, be very careful about making sure the type used is consistent across all products. If your schema ever changes, you'll need to first change all your products and then manually kick off an index rebuild.

Facet values maximum display – Facet values are capped at 50 to ensure optimal performance. Even if more values are indexed, only the first 50 will be displayed. To manage this, it is recommended to apply filters to reduce the number of results and, consequently, the number of facet values. This approach not only enhances performance but also improves the user experience by preventing overwhelming lists of options.

Facet values case sensitivity – Facet values will appear in lowercase, even if the xp value includes uppercase characters. If you need values displayed differently, apply a transformation using JavaScript or CSS on the frontend.

Use strings instead of decimals for accuracy – Decimal facets are not supported due to a limitation related to how floating point decimals are stored. In some scenarios, the stored value may differ from the value represented in the facet. To ensure accuracy, we recommend using strings instead of decimals for facet values.

Related reading

• XP best practices
• Using extended properties