Outfits and Similar 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 starts from the products currently in the basket.

For what outfits are and how they are assembled, see How outfits work in the Integration Overview.

Note

The JavaScript calls described on this page require Integrated Tracking with 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

• 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.

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 content, but the parameter names differ in places, and the basket contents are handled differently. The Applies to column in the parameter table shows 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

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 anchor item is excluded from the returned outfits by default.

Identifiers are interpreted as product codes. To pass an SKU, EAN, GTIN, or internal Mapp Fashion identifier, set identifier_type as well.

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

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 anchor item is excluded by default.

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

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

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

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

wtSmart.extension.fashion.call("items", "top", {
  department: "female",
  garment_format: "detailed",
  max_items: 8,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

HTTP

GET https://api.your-domain.com/api/v2/items/top?department=female&max_items=8&garment_format=detailed

Basket Items

Returns recommendations for the products currently in a shopper's basket. Use it on basket, wishlist, or checkout pages to suggest additional items before the shopper completes the purchase.

In the JavaScript client library you do not pass any product codes. The basket contents are taken from the product data that the Mapp Fashion extension already collects, so product tracking must be in place on the basket page. When you call the endpoint directly over HTTP, pass the basket products in the ids parameter.

Products that are in the basket are removed from the recommendations, so shoppers never see items they have already added.

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

wtSmart.extension.fashion.call("items", "basket", {
  garment_format: "detailed",
  max_items: 8,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

HTTP

GET https://api.your-domain.com/api/v2/items/basket?ids=PC12345&ids=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.

Note

Additional parameters are passed through directly as query parameters, even if they are not listed in the client configuration.

Response

Every response contains an event identifier, the recommended items, and a garment_data section. With garment_format set to simple, garment_data stays empty and only the item identifiers are returned. Request detailed when you render product cards and need names, prices, and images.

The example below shows a similar response requested with garment_format=simple.

{
  "event_id": "6a959a3a5e29c89df1d8ddbe",
  "source": {
    "garment_id": "PC12345",
    "ancillary_product_code": "PC123"
  },
  "garment_data": [],
  "similar_items": {
    "content_id": "6a959a3b5e29c89df1d8ddbf",
    "items": [
      {
        "garment_id": "PC23456",
        "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.

Note

The content_id of a returned set is required for Recommendation Tracking. 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:

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, stores, and include_user_data are no longer supported.

• Empty sections are omitted from the response instead of being returned as empty keys.