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 in the Integration Overview.

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

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

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 (Style ID). To pass a Variant ID, a barcode or the 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 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

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", {
  ids: ["PC12345", "PC23456"],
  garment_format: "detailed",
  max_items: 8,
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

HTTP

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.

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:

response_id is the event_id of the HTTP response. 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

Items in the Detailed Format

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

{
  "event_id": "6a959a3a5e29c89df1d8ddbe",
  "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.

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