--- title: "Recommendation Items" slug: "mapp-fashion-recommendation-items" description: "How to retrieve Mapp Fashion outfits, similar, top and basket items via Smart Pixel or HTTP, and how to handle the anchor item in outfit responses." tags: ["Mapp Fashion", "Outfit Retrieval", "Item Recommendations"] status: "update" updated: 2026-10-21T11:37:06Z published: 2026-10-21T11:37:06Z canonical: "docs.mapp.com/mapp-fashion-recommendation-items" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.mapp.com/llms.txt > Use this file to discover all available pages before exploring further. # Recommendation Items ## Overview This page describes how to retrieve Mapp Fashion recommendation items from your website or frontend. Five item types are available. Three of them start from a specific product, for example on a product detail page. `top` needs no product at all and follows the shopper's preferences. `basket` also follows the shopper's preferences and leaves out the products in the basket. For what outfits are and how they are assembled, see [How outfits work](/v1/docs/mapp-fashion-introduction#how-outfits-work) in the Integration Overview. > [!NOTE] > Note > > The JavaScript calls described on this page require the Mapp Fashion extension for the Mapp Intelligence Smart Pixel. They are not available in a Standalone Tracking setup. --- ## Key facts - Retrieves recommendation content only; no tracking is performed on retrieval - Interaction tracking is handled separately via [Recommendation Tracking](/v1/docs/recommendation-tracking-fashion) - Each item type has its own call and its own endpoint - Item order and grouping must be preserved for correct interaction tracking - Typically used in PDP implementations, basket pages, landing pages, or headless frontends --- ## Available Item Types Choose the item type that matches the page you are building. | **Item type** | Typical use | Starting point | Endpoint | | --- | --- | --- | --- | | `outfits` | Complete looks built around a product, on the product detail page | Anchor item | `/api/v2/items/outfits` | | `partner_outfits` | Outfits you supplied yourself, such as campaign or editorial looks | Anchor item | `/api/v2/items/partner_outfits` | | `similar` | Alternatives to the product a shopper is viewing | Anchor item | `/api/v2/items/similar` | | `top` | Personalized entry points such as homepages and landing pages | Shopper profile | `/api/v2/items/top` | | `basket` | Add-on suggestions on basket, wishlist, or checkout pages | Basket contents | `/api/v2/items/basket` | > [!NOTE] > Note > > Outfits, partner outfits, and similar items always require a valid anchor item. There is no fallback logic: an identifier that Mapp Fashion does not recognize results in an empty or irrelevant response. --- ## Retrieval Approaches Recommendation items can be retrieved in two ways. Both return the same recommendations, but some parameter names and the response format differ. The *Applies to* column in the parameter table and the Response section show where. ### JavaScript client library Use this approach when recommendations are rendered client-side and Integrated Tracking is in place. The Smart Pixel handles the request, the shopper context, and the response. ### Direct HTTP requests Use this approach for server-side rendering, headless setups, or backend integrations. All request properties are passed as query parameters. > [!NOTE] > Note > > The exact domain depends on your Mapp Fashion environment. A separate host is configured per partner. --- ## Outfits Returns complete looks built around a single product. Use it on product detail pages to show how an item can be worn. Outfits are grouped by occasion. The HTTP response excludes the anchor item from the outfits by default. The JavaScript client library returns it as the first item of each outfit. Identifiers are interpreted as product codes (Style ID). To pass a Variant ID, a barcode or the internal Mapp Fashion identifier, set `identifier_type` as well. > [!WARNING] > Warning > > When you use the JavaScript client library, the first item of each outfit is the anchor item, which is the product you passed in `item_id`. If your page already shows this product, for example as the main product on the product detail page, remove this item before you render the outfit. Otherwise the product appears in its own outfit. Keep the remaining items in the order in which they were returned. ### JavaScript ```javascript wtSmart.extension.fashion.call("items", "outfits", {  item_id: "YOUR_PRODUCT_CODE",  placement_id: "A_UUID_PROVIDED_BY_MAPP",  response_format: "detailed",  onSuccess: (data) => {},  onFailure: (err) => {}, }); ``` ### HTTP ```bash GET https://api.your-domain.com/api/v2/items/outfits?id=PC12345&garment_format=detailed ``` --- ## Partner Outfits Returns outfits that you supplied yourself instead of outfits generated by Mapp Fashion. Use it when you want full control over specific looks, such as campaign or editorial styling. Partner outfits are not assigned to an occasion, and `outfits_per_occasion` has no effect on them. How many outfits are returned depends on the looks you supplied. As with outfits, the HTTP response excludes the anchor item by default, while the JavaScript client library returns it as the first item of each outfit. ### JavaScript ```javascript wtSmart.extension.fashion.call("items", "partner_outfits", {  item_id: "YOUR_PRODUCT_CODE",  placement_id: "A_UUID_PROVIDED_BY_MAPP",  response_format: "detailed",  onSuccess: (data) => {},  onFailure: (err) => {}, }); ``` ### HTTP ```bash GET https://api.your-domain.com/api/v2/items/partner_outfits?id=PC12345&garment_format=detailed ``` --- ## Similar Items Returns products that are comparable to the product a shopper is viewing. Use it to offer alternatives when an item is not the right fit, is out of stock, or is outside the shopper's price range. ### JavaScript ```javascript wtSmart.extension.fashion.call("items", "similar", {  item_id: "YOUR_PRODUCT_CODE",  placement_id: "A_UUID_PROVIDED_BY_MAPP",  response_format: "detailed",  onSuccess: (data) => {},  onFailure: (err) => {}, }); ``` ### HTTP ```bash GET https://api.your-domain.com/api/v2/items/similar?id=PC12345&garment_format=detailed ``` --- ## Top Items Returns personalized recommendations without a starting product. Use it early in the customer journey, before a shopper reaches a product detail page, for example on the homepage or at the top of a product listing page. Recommendations are based on how likely a shopper is to buy items with particular attributes, not on the products they viewed most recently. For shoppers with no history, the call returns broadly relevant top products, so it can be used for new and anonymous visitors as well. Without `department`, recommendations are drawn from the female department. Set the value explicitly to match the page. ### JavaScript ```javascript wtSmart.extension.fashion.call("items", "top", {  department: "female",  garment_format: "detailed",  max_items: 8,  onSuccess: (data) => {},  onFailure: (err) => {}, }); ``` ### HTTP ```bash GET https://api.your-domain.com/api/v2/items/top?department=female&max_items=8&garment_format=detailed ``` --- ## Basket Items Returns personalized recommendations like `top`, not items similar to the basket contents. The department is taken from the products in the basket. Use it on basket, wishlist, or checkout pages to suggest additional items before the shopper completes the purchase. Pass the products in the basket in `ids`, in the JavaScript client library as well as over HTTP. Without `ids`, or if none of them can be resolved, you still get recommendations. Products that are in the basket are removed from the recommendations, so shoppers never see items they have already added. > [!NOTE] > Note > > A maximum of 10 basket products is taken into account. This is the input limit and is independent of `max_items`, which controls how many recommendations are returned. ### JavaScript ```javascript wtSmart.extension.fashion.call("items", "basket", {  ids: ["PC12345", "PC23456"],  garment_format: "detailed",  max_items: 8,  onSuccess: (data) => {},  onFailure: (err) => {}, }); ``` ### HTTP ```bash GET https://api.your-domain.com/api/v2/items/basket?ids=PC12345,PC23456&garment_format=detailed ``` --- ## Request Parameters The following parameters control which content is returned and how items are represented in the response. Not every parameter applies to every item type. | Parameter | Applies to | Values and default | Description | | --- | --- | --- | --- | | `id` | `outfits`, `partner_outfits`, `similar` | String | Required. Identifier of the anchor item. Its interpretation is controlled by `identifier_type`. In the JavaScript client library this property is called `item_id`. | | `ids` | `basket` | Comma-separated list, for example `ids=PC12345,PC23456`, maximum 10 values. In the JavaScript client library, an array is also accepted. | Identifiers of the products in the basket. These products are excluded from the recommendations, and the department is taken from them. If the list is empty or none of the identifiers can be resolved, you still get recommendations. | | `identifier_type` | `outfits`, `partner_outfits`, `similar`, `basket` | `product-code` (default), `sku`, `gtin`, `fashion-id` (not for `basket`) | Controls how the identifiers are interpreted: `product-code` is your Style ID (style and color), `sku` your Variant ID, `gtin` the barcode, for example EAN-13, `fashion-id` the internal Mapp Fashion identifier. See [Product and Customer Identifiers](/v1/docs/mapp-fashion-product-and-customer-identifiers). | | `garment_format` | All | `simple` (default), `detailed` | Format of the returned item data. `simple` returns identifiers only, `detailed` adds product metadata such as name, price, and images. In the JavaScript client library, `outfits`, `partner_outfits`, `similar` use the property name `response_format` instead. There, `simple` is not supported and the default is `detailed`. | | `max_items` | `similar`, `top`, `basket` | 1 to 20, default 6 | Number of items to return. | | `outfits_per_occasion` | `outfits`, `partner_outfits` | 1 to 4, default 2 | Number of outfits to return per occasion. | | `exclude_source_garment` | `outfits`, `partner_outfits`, `similar` | Boolean, default `true` | Whether the anchor item is removed from the HTTP response. The JavaScript client library always returns it as the first item of each outfit. | | `excluded_ids` | `similar`, `top`, `basket` | Comma-separated list, for example `excluded_ids=PC12345,PC23456` | Products to exclude from the results, in addition to the ones already excluded automatically. | | `department` | `top` | `female` (default), `male`, `girls`, `boys`, `unisex` | Department the recommendations are drawn from. | | `sort` | `basket` | `price` | Sorts the recommendations by price. Set the order with `direction`. | | `direction` | `basket` | `asc`, `desc` (default) | Sort order for `sort`. | | `max_reduced_by` | `outfits`, `partner_outfits`, `similar`, `top`, `basket` | 1 to 100, no filter by default | Maximum price reduction of returned items, in percent. Only works if your product data contains discount information. | | `placement_id` | `outfits`, `partner_outfits`, `similar` (JavaScript only) | UUID | Identifies the placement for reporting. The value is provided by Mapp. | | `include_fashion_ids` | `outfits`, `partner_outfits`, `similar`, `top` | Boolean, default `false` | Whether internal Mapp Fashion identifiers are included in the response. Set to `true` if you use Recommendation Tracking, which needs `raw_garment_id`. | | `include_user_data` | `basket` | Boolean, default `false` | Whether a `user` object with information about the shopper is included in the response. | | `locale` | All | String, for example `en_GB` | Restricts results to this locale, if provided in the feed. | | `language` | All | String, for example `en` | Localizes the response to this language, if provided in the feed. | | `onSuccess` | All (JavaScript only) | Callback | Called with the response data. | | `onFailure` | All (JavaScript only) | Callback | Called when the request fails. | > [!NOTE] > Note > > Additional parameters are passed through directly as query parameters, even if they are not listed in the client configuration. --- ## Response The JavaScript client library and direct HTTP requests return the same recommendations in different formats. The JavaScript client library adds the product data to each item and renames some fields. ### JavaScript Client Library `onSuccess` receives an object with the following properties: | Item type | Properties | | --- | --- | | `outfits` | `response_id`, `outfits`: list of outfits, each with `content_id`, `occasion` and `items`. The first item of each outfit is the anchor item. Remove it before rendering if your page already shows this product. | | `partner_outfits` | `response_id`, `partner_outfits`: same structure as `outfits`. | | `similar` | `response_id`, `content_id`, `items`. If no set of similar items is returned, the object is empty. | | `top` | `response_id`, `content_id`, `top_items`. | | `basket` | `response_id`, `recommendations` and, with `include_user_data=true`, `user`. `content_id` is always empty because the API returns no set ID for basket. | `response_id` is the `event_id` of the HTTP response. All item types also return `currency`, the currency of the prices for the requested locale, for example `GBP`. It is `null` if your product data contains no currency. The items have one of two formats, depending on `garment_format` or `response_format`. To match items with your product data, use `style_id`. It is returned in both formats. #### Items in the Simple Format | Field | Type | Description | | --- | --- | --- | | `id` | String | Identifier of the item. It has the same type as the identifiers in the request (`identifier_type`), by default the Style ID. | | `style_id` | String | Style ID (product code). | | `dressipi_item_id` | Number | Internal Mapp Fashion ID. Only filled if `include_fashion_ids` is `true`, otherwise `0`. | | `product_id` | String | Product ID (product level), if your product data contains it. | | `available_variant_ids` | Array | Variant IDs (SKUs) of the item that are in stock. | #### Items in the Detailed Format | Field | Type | Description | | --- | --- | --- | | `dressipi_item_id` | Number | Internal Mapp Fashion ID. | | `style_id` | String | Style ID (product code). | | `product_id` | String | Product ID (product level), if your product data contains it. | | `ancillary_product_code` | String | Alternative product code. Empty if your product data does not contain it. | | `available_variant_ids` | Array | Variant IDs (SKUs) of the item that are in stock. | | `name` | String | Product name. | | `brand_name` | String | Brand name. | | `url` | String | URL of the product page. | | `price` | String | Current price. | | `old_price` | String | Previous price, if the product is reduced. | | `status` | String | `in stock` or `out of stock`. | | `category_id` | Number | Mapp Fashion garment category ID. | | `category_name` | String | Mapp Fashion garment category name. | | `image_url` | String | URL of the main image. | | `images` | Array | All image URLs from the product feed. | | `thumbnail_image_url` | String | URL of the thumbnail. If there is none, the first image from the feed or the main image is used. | | `best_model_image` | String | URL of the selected image with a model, if available. | | `best_product_image` | String | URL of the selected product image, if available. | | `has_outfits` | Boolean | Whether outfits are available for the item. | > [!NOTE] > Note > > In the detailed format, items without product data are left out. The list can therefore contain fewer items than requested. ### HTTP The HTTP response contains `event_id`, `currency`, `garment_data`, `available_skus` and the recommended items under one key per item type: `outfits`, `partner_outfits`, `similar_items`, `top_items`, or `recommendations` for `basket`. Item-based types also return the anchor item as `source`. `garment_data` contains the product data and is only filled in the `detailed` format. `available_skus` lists the in-stock Variant IDs of each recommended item, keyed by `garment_id`. The example below shows a `similar` response requested with `garment_format=simple`. ```json {  "event_id": "6a959a3a5e29c89df1d8ddbe",  "currency": "GBP",  "source": {    "garment_id": "PC12345",    "raw_garment_id": 5746027,    "product_id": "P123",    "ancillary_product_code": "PC123"  },  "garment_data": [],  "available_skus": [    { "garment_id": "PC23456", "skus": ["PC23456-36", "PC23456-38"] }  ],  "similar_items": {    "content_id": "6a959a3b5e29c89df1d8ddbf",    "items": [      {        "garment_id": "PC23456",        "product_id": "P234",        "ancillary_product_code": "PC234"      }    ]  } } ``` Outfit responses are structured as groups of items instead of a flat list. For the full response schema of each item type, see the [Mapp Fashion API documentation](/v1/apidocs/mapp-fashion-api-documentation). > [!NOTE] > Note > > The `content_id` of a returned set is required for [Recommendation Tracking](/v1/docs/recommendation-tracking-fashion). Keep the items in the order in which they were returned. --- ## Migrating from the Combined Call Earlier integrations retrieved outfits, partner outfits, and similar items in a single call that used a `methods` parameter: ```javascript wtSmart.extension.fashion.call("related", "items", {  item_id: "YOUR_PRODUCT_CODE",  methods: ["outfits", "partner_outfits", "similar_items"],  try_all_methods: true,  onSuccess: (data) => {},  onFailure: (err) => {}, }); ``` This call still works. Internally it is split into one request per method, so it offers no performance benefit over calling the item types individually. New integrations should use the individual calls described on this page. When migrating, note the following changes: - The call is now `call("items", "<item type>", { … })` instead of `call("related", "items", { … })`, with one item type per call. The former methods correspond to today's item types, and `similar_items` is now called `similar`. - The parameters `methods` and `try_all_methods` no longer exist. - `max_similar_items` is now called `max_items`. - `include_dressipi_ids` is now called `include_fashion_ids`, and its default changed from `true` to `false`. - The default of `garment_format` changed from `detailed` to `simple`. If you render product cards, set `detailed` explicitly. - `garment_format` accepts `simple` and `detailed`. The former value `retailer_ids` corresponds to `simple`; `document` is no longer available. - Without `identifier_type`, identifiers are now interpreted as product codes. Previously the internal Mapp Fashion identifier was assumed. To keep sending internal identifiers, set `identifier_type` to `fashion-id`. - `identifier_type` no longer accepts `dressipi-id` and `ancillary-product-code`. Use `fashion-id` instead of `dressipi-id`. - The parameters `sku_refinement`, `fields`, and `stores` are no longer supported. `include_user_data` is only available for `basket`. - Empty sections are omitted from the response instead of being returned as empty keys.