Multilevel Facet

You can build a hierarchy in your facet values to enable multi-level navigation and filtering. This pattern is great for very long lists of values and to improve discoverability: your users can browse up and down in the levels to refine their searches.

Property	Description
`multilevel`	Hierarchical facets configured on the hierarchical field(s). Facets are grouped under their respective types to simplify deserialization. Currently supported types include MultiLevel Facets, Text Facets, and Range Facets.
`list`	Array of hierarchical facets configured on the hierarchical fields in the Unbxd Console.
`values`	Contains all unique values for the sub-categories available for the query, along with their respective product counts. For example, for the query `mobile`, values can include `Mobiles & Tablets (300)` and `Smartphones (36)`. These values act as filters that shoppers can select to refine search results.
`level`	Depth level of the multilevel hierarchical field.
`filterField`	The field on which the hierarchical facet is created.
`breadcrumb`	Position within the hierarchical field where the results appear.

No Facet Selected

When no facets are selected (or no filters are passed), the API will respond with facets belonging to the field's first level.

Sample Request

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/search?&q=mobile&version=V2

Sample Response

{
  "searchMetaData": {},
  "response": {},
  "facets": {
    "multilevel": {
      "list": [
        {
          "filterField": "productType",
          "level": 1,
          "id": "100",
          "displayName": "Product Type",
          "position": 1,
          "values": [
            { "id": "HO", "name": "Home", "count": 31 },
            { "id": "J", "name": "Jewelry", "count": 22 }
          ],
          "breadcrumb": {}
        },
        {
          "filterField": "theme",
          "level": 1,
          "id": "200",
          "displayName": "Theme",
          "position": 2,
          "values": [
            { "id": "12", "name": "Animals", "count": 34 },
            { "id": "13", "name": "Birds", "count": 21 }
          ],
          "breadcrumb": {}
        }
      ]
    }
  }
}

First Level of Facets Selected

When first level of facets are selected, the API will respond with the second level of field value.

Sample Request

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/
search?&q=mobile&version=V2&filter=productType:"Home"

Sample Response

{
  "searchMetaData": {},
  "response": {},
  "facets": {
    "multilevel": {
      "list": [
        {
          "filterField": "productType",
          "level": 2,
          "id": "100",
          "displayName": "Product Type",
          "position": 1,
          "values": [
            { "id": "HO001", "name": "Decor", "count": 15 },
            { "id": "HO002", "name": "Outdoors", "count": 16 }
          ],
          "breadcrumb": {
            "filterField": "productType",
            "values": [{ "id": "HO", "name": "Home" }],
            "level": 1
          }
        },
        {
          "filterField": "theme",
          "level": 1,
          "id": "200",
          "displayName": "Theme",
          "position": 2,
          "values": [
            { "id": "12", "name": "Animals", "count": 34 },
            { "id": "13", "name": "Birds", "count": 21 }
          ],
          "breadcrumb": {
            "filterField": "theme",
            "values": [{ "id": "21", "name": "MNP" }],
            "child": {
              "filterField": "theme",
              "values": [{ "id": "23", "name": "ZZZ" }],
              "level": 2
            },
            "level": 1
          }
        }
      ]
    }
  }
}

Second Level of Facets Selected

When the second level of facets is selected, the API will respond with the third level of field values.

Sample Request

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/
search?&q=mobile&version=V2&&filter=productType:"Home>Decor"

Sample Response

{
  "searchMetaData": {},
  "response": {},
  "facets": {
    "multilevel": {
      "list": [
        {
          "filterField": "productType",
          "level": 3,
          "id": "100",
          "displayName": "Product Type",
          "position": 1,
          "values": [
            { "id": "HO011", "name": "Wall Decor", "count": 10 },
            { "id": "Ho012", "name": "Floor Decor", "count": 5 }
          ],
          "breadcrumb": {
            "filterField": "productType",
            "values": [{ "id": "HO", "name": "Home" }],
            "child": {
              "filterField": "productType",
              "values": [{ "id": "HO001", "name": "Decor" }],
              "level": 2
            },
            "level": 1
          }
        },
        {
          "filterField": "theme",
          "level": 1,
          "id": "200",
          "displayName": "Theme",
          "position": 2,
          "values": [
            { "id": "12", "name": "Animals", "count": 34 },
            { "id": "13", "name": "Birds", "count": 21 }
          ],
          "breadcrumb": {
            "filterField": "theme",
            "values": [{ "id": "21", "name": "MNP" }],
            "child": {
              "filterField": "theme",
              "values": [{ "id": "23", "name": "ZZZ" }],
              "level": 2
            },
            "level": 1
          }
        }
      ]
    }
  }
}

Value from Last Level Selected

When the value from the last level is selected, API will respond back with the sibling field values from the last level

Sample Request

Here is the API when the “Home>Decor>Wall Decor” is selected:

Sample Request

https://search.unbxd.io/63e6578fcb4382aee0eea117aba3a227/docs-unbxd700181508846765/
search?&q=mobile&version=V2&filter=productType:"Home>Decor>Wall Decor"

Sample Response

{
  "searchMetaData": {},
  "response": {},
  "facets": {
    "multilevel": {
      "list": [
        {
          "filterField": "productType",
          "level": 3,
          "id": "100",
          "displayName": "Product Type",
          "position": 1,
          "values": [
            { "id": "HO011", "name": "Wall Decor", "count": 10 },
            { "id": "Ho012", "name": "Floor Decor", "count": 5 }
          ],
          "breadcrumb": {
            "filterField": "productType",
            "values": [{ "id": "HO", "name": "Home" }],
            "child": {
              "filterField": "productType",
              "values": [{ "id": "HO001", "name": "Decor" }],
              "child": {
                "filterField": "productType",
                "values": [{ "id": "HO011", "name": "Wall Decor" }],
                "level": 3
              },
              "level": 2
            },
            "level": 1
          }
        },
        {
          "filterField": "theme",
          "level": 1,
          "id": "200",
          "displayName": "Theme",
          "position": 2,
          "values": [
            { "id": "12", "name": "Animals", "count": 34 },
            { "id": "13", "name": "Birds", "count": 21 }
          ],
          "breadcrumb": {
            "filterField": "theme",
            "values": [{ "id": "21", "name": "MNP" }],
            "child": {
              "filterField": "theme",
              "values": [{ "id": "23", "name": "ZZZ" }],
              "level": 2
            },
            "level": 1
          }
        }
      ]
    }
  }
}

Multi-Select Across Multiple Trees

Shoppers can now select multiple categories across different parent trees in a single request, and all category branches stay visible after a selection is made. This resolves two earlier limitations of the multilevel facet:

Only one category path could be selected at a time.
Sibling and unrelated branches were hidden after selection.
Both are resolved with a single parameter.

How to Enable

Pass facet.multilevel.multiselect=true in the existing Search API request.

No feed or schema changes required.
Opt-in per request, default behavior is unchanged.

Behavior Summary

Persistent display: Sibling and unrelated branches stay visible post-selection.
Multi-tree selection: Multiple categories from different parent trees can be active at once.
Filter logic: OR across selected paths (mirrors facet.multiselect for flat text facets).
Breadcrumb: Returns all active paths as removable chips.
Counts: Reflects what you would add rather than the post-filter set, consistent with existing multiselect behavior.
Example: A shopper restocking her beauty routine wants both lipsticks and serums in one view.

Before, after selecting Makeup > Lipstick:

Makeup
  ✓ Lipstick
      Light Lipstick
      Dark Lipstick
  Mascara (hidden)
  Foundation (hidden)
Skincare (entire branch hidden)
Fragrance (entire branch hidden)

Results: Lipsticks only. Active chips: [Makeup > Lipstick > ...]

To also see serums, she has to clear her selection and search again.

After, selecting Makeup > Lipstick OR Skincare > Serum:

Makeup
  ✓ Lipstick
      Light Lipstick
      Dark Lipstick
    Mascara
    Foundation
Skincare
    Moisturizer
  ✓ Serum
     Sunscreen
Fragrance

Results: Lipsticks + Serums. Active chips: [Makeup > Lipstick > ...] [Skincare > Serum > ...]

All branches stay visible. She could also add Fragrance > Women's Perfume as a third filter.

Sample Request

https://search.unbxd.io/<api_key>/<site_key>/search?q=*&version=V2&filter=productType:"Makeup>Lipstick"&filter=productType:"Skincare>Serum"&facet.multilevel.multiselect=true

👍
Recommendation
Marketplaces and broad-catalog storefronts, beauty, department stores, multi-brand retailers, where cross-category browsing is common.