Faceted Search

Overview

This page describes how to retrieve product recommendations with Mapp Fashion for product discovery use cases.

The facetted endpoint returns a ranked list of recommended items. By applying facets, the result set can be refined using dimensions such as category, brand, price, or features.

Faceted Search allows you to refine recommendations using dimensions such as category, brand, price, or features. The API also supports facet counts for guided navigation and discovery experiences.

Key facts

• The endpoint retrieves recommendation content only; no impression or interaction tracking is triggered by the request itself  

  • Interaction tracking must be implemented separately using Recommendation Tracking

• Supports single and multiple facet filters, including range-based filters (for example, price)

• Supports pagination via query parameters to incrementally load result sets

• Can return facet metadata (such as value counts) to support frontend filtering and navigation

• Commonly used for Product Listing Pages (PLPs), category pages, and other discovery-oriented views

Endpoint

Use the following endpoint to retrieve faceted recommendations or default recommendations without facets.

HTTP

POST /api/recommendations/facetted?per_page=10&page=2&garment_format=detailed

• This endpoint is used for both default (unfiltered) recommendations and faceted search requests.

• The endpoint name uses the spelling facetted, which is reflected in the API path.

• The request behavior is controlled by the facets object in the request body, while pagination and response formatting are handled via query parameters.

Default recommendations (no facets)

When no facets are applied, the facetted endpoint returns a ranked list of recommended items based on the default recommendation logic for the given placement.

To retrieve this default result set without applying any filters, send an empty facets array.

This explicitly signals that no facet-based filtering should be applied.

wtSmart.extension.fashion.call("facetted", "search", {
  facets: [],
  placement_id: "A_UUID_PROVIDED_BY_MAPP",
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

Facet Filters

The following filter dimensions are supported for faceted search and default (unfiltered) recommendations. These dimensions define how results can be filtered or aggregated.

• garment_category

• brand

• occasion

• must_have

• retailer_labels: Depends on the data present in the product feed. Allows you to query against fields in the product feed consumed (these should be agreed with Mapp).

• store: If Mapp has been provided with per-store availability data, this filters or aggregates on availability by store

• feature_ids: Mapp Fashion feature IDs

• not_features_ids: Exclude results with these feature IDs.

• price: supports ranges

• reduced_by: Percentage discount filter (0–100).

The availability and behavior of certain facets depend on the data provided in the product feed and the project setup.

Facets such as retailer_labels or store are only effective if the corresponding data is present and configured. Providing unsupported or empty facet values does not result in an error, but may return empty or reduced result sets.

Request Parameters

The following query parameters control pagination and response formatting.

Request Body (Facets)

Facets are defined in the request body and control how recommendation results are filtered. Each facet targets a specific dimension and can either define allowed values or numeric ranges.

Facet combination logic

• Multiple facets in a request are combined using logical AND.  

• Multiple values within a single facet are combined using logical OR.  

• When a facet supports multiple ranges (for example price), the ranges are evaluated as logical OR.

Single Filter Facet

Use a single filter facet when filtering by discrete values within one dimension, such as specific brands or categories.

{
  "name": "brand",
  "value": ["Nike", "Adidas"]
}

Multi Filter Facet

Use a multi filter facet when a dimension supports numeric values (for example price) or when multiple value ranges should be applied within a single request.

{
  "name": "price",
  "filters": [
    { "from": 20, "to": 50 },
    { "from": 70 }
  ]
}

wtSmart.extension.fashion.call("facetted", "search", {
  facets: [
    {
      name: "retailer_labels", // values depend on the configured product feed
      value: ["Womenswear > Dresses"]
    },
    {
      name: "feature_ids", // these are Mapp Fashion feature ids
      filters: [
        {"value": [1,2]},
        {"value": [3,4]}
      ]
    },
    {
      name: "price",
      filters: [
        {
          from: 50,
          to: 100
        }
      ],
      ranges: [ // alternatively, multiple ranges can be present as follows:
        {to: 50},
        {from: 50, to: 100},
        {from: 100}
      ]
    }
  ],
  placement_id: "A_UUID_PROVIDED_BY_MAPP",
  onSuccess: (data) => {
  },
  onFailure: (err) => {},
});

Response Structure

The response contains multiple fields that serve different purposes.

For most frontend implementations, the items array and the pagination object are the primary fields used to render product lists and navigation.

Fields such as response_id, content_id, and event_id are mainly relevant for debugging or tracking integration and can typically be ignored during initial UI rendering.

High-level Example

The following example shows a simplified response structure. Additional fields may be present and can be ignored unless explicitly documented below.

{
  "items": [
    {
      "id": "TKBETTYMERINOWOOLBlackBlack",
      "dressipi_item_id": 5307387
    }
  ],
  "pagination": {
    "total_pages": 80,
    "total_items": 960,
    "current_page": 1
  }
}

Detailed Response Structure (FacettedResponse)

Pagination Metadata

DetailedItem

The DetailedItem object contains the product attributes required for rendering recommendation tiles or product cards.