Faceted Search

Faceted Search returns Mapp Fashion recommendations for product listing pages and other browsing pages. You narrow the results with filters, request counts per filter value to build a filter navigation, and load the results page by page.

Key Facts

• The call only retrieves recommendations. Interactions are tracked separately with Recommendation Tracking.

• Results are personalized if the shopper is known. Otherwise, generally relevant products are returned.

• Filters of different names are combined with AND. Values within one filter are combined with OR.

• The endpoint path uses the spelling facetted.

Request

JavaScript

wtSmart.extension.fashion.call("facetted", "search", {
  filters: {
    garment_category: ["1"],
    brand: ["BRAND_ID_1", "BRAND_ID_2"],
    min_price: 20,
    max_price: 80,
  },
  aggregations: [
    { name: "brand", size: 10 },
    { name: "price", ranges: [{ to: 50 }, { from: 50, to: 100 }, { from: 100 }] },
  ],
  department: "female",
  per_page: 24,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

HTTP

POST https://api.your-domain.com/api/v2/facetted?department=female&per_page=24&garment_format=detailed
Content-Type: application/json

{
  "filters": {
    "garment_category": ["1"],
    "brand": ["BRAND_ID_1", "BRAND_ID_2"],
    "min_price": 20,
    "max_price": 80
  },
  "aggregations": [
    { "name": "brand", "size": 10 },
    { "name": "price", "ranges": [{ "to": 50 }, { "from": 50, "to": 100 }, { "from": 100 }] }
  ]
}

Over HTTP, filters, aggregations and root_event_id are sent in the request body. All other parameters are query parameters. In the JavaScript client library, all of them are properties of the call.

The v1 endpoint /api/recommendations/facetted remains available with its previous request format. For new integrations, use v2.

Filters

Pass filters in filters, keyed by filter name. Without filters, the call returns the default ranked list for the department.

Facet Counts

To build a filter navigation, list the facets you need in aggregations. For each facet, the response contains buckets with a count. The count shows how many results the same request would return if it were also filtered by that bucket.

reduced_by, product_ids, feature_ids, not_feature_ids can only be used as filters, not as facets.

Pagination

Set the page size with per_page and the page with page. For the second and every later page, also pass the ID of the first response as root_event_id: response_id in the JavaScript client library, event_id over HTTP.

wtSmart.extension.fashion.call("facetted", "search", {
  filters: { garment_category: ["1"] },
  per_page: 24,
  page: 2,
  root_event_id: firstPage.response_id,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

Request Parameters

Response

JavaScript Client Library

{
  "response_id": "6a959a3a5e29c89df1d8ddbe",
  "content_id": "6a959a3b5e29c89df1d8ddbf",
  "currency": "GBP",
  "items": [
    {
      "dressipi_item_id": 5307387,
      "style_id": "TKBETTY-BLACK",
      "name": "Merino Wool Jumper",
      "price": "49.99"
    }
  ],
  "facets": [
    {
      "name": "brand",
      "buckets": [{ "id": "BRAND_ID_1", "name": "Some Brand", "count": 42 }]
    },
    {
      "name": "price",
      "buckets": [{ "to": 50, "count": 120 }, { "from": 50, "to": 100, "count": 64 }]
    }
  ],
  "pagination": { "current_page": 1, "last_page": 40, "total_items": 960 }
}

The example shows only some of the item fields.

HTTP

The HTTP response contains event_id, currency, facets, pagination and recommendations. recommendations holds the content_id and the items. Each item contains garment_id (Style ID), product_code, product_id (Product ID), ancillary_product_code, available_skus with the in-stock Variant IDs and, with include_fashion_ids=true, raw_garment_id. In the detailed format, the product data is returned in garment_data. pagination contains current_page, total_pages and total_entries. For the full schema, see the Mapp Fashion API.

Changes to the Previous Request Format

Since the October 2026 update of the Mapp Fashion extension, the JavaScript call uses the v2 endpoint and a new request format. The update is loaded automatically. If your implementation passes a facets list, change it as follows:

• facets is replaced by filters, an object keyed by filter name, and aggregations, the list of facets to count.

• Price ranges are filtered with min_price and max_price and counted with a price facet.

• not_features_ids is now called not_feature_ids.

• must_have is no longer available. season is new.

Direct HTTP requests to the v1 endpoint /api/recommendations/facetted are not affected. If you switch them to /api/v2/facetted, apply the same changes. v2 no longer accepts canonical_only, fields, device_type and returns content_id inside recommendations.