Outfits and Similar Items

Overview

This page describes how to retrieve Mapp Fashion outfits and similar items for a given product.

This endpoint is used for item-based recommendation use cases, where a specific product serves as the starting point for related content.

Important

This endpoint always requires a valid anchor item (item_id).

There is no fallback logic. Invalid identifiers will result in empty or irrelevant responses.

Key facts

• Retrieves recommendation content only; no tracking is performed on retrieval

• Interaction tracking is handled separately via Recommendation Tracking

• Used to render outfits, partner outfits, and similar item lists

• Content can be requested individually or combined in a single call

• Item order and grouping must be preserved for correct interaction tracking

• Typically used in PDP implementations or headless frontends

Retrieval Approaches

Outfits and similar items can be retrieved using the same underlying API.

Choose the approach based on your integration setup and rendering strategy.

• JavaScript client library

  Use when recommendations are rendered client-side via integrated tracking.

• Direct HTTP requests

  Use for server-side rendering, headless setups, or backend integrations.

Both approaches return the same response structures and support the same request parameters.

Endpoint

GET /api/items/{item_id}/related

Note

The exact domain depends on your Mapp Fashion environment.

All request properties are passed as query parameters.

Important

This endpoint depends on exact identifier matching.

Make sure item_id and identifier_type match your product feed exactly. If they do not match, the request will return no results.

There is no fallback logic for partial or incorrect identifiers.

Request Parameters

The following parameters control which related content is returned and how items are represented in the response.

The request parameters can be grouped by their purpose:

• Required

  • item_id

• Content selection

  • methods

  • try_all_methods

• Result shaping

  • response_format / garment_format

  • outfits_per_occasion

  • max_similar_items

  • max_reduced_by

• Identification and context

  • identifier_type

  • locale

Note

Any additional parameters (for example locale) are passed through directly as query parameters, even if not explicitly defined in the client configuration.

Parameter Reference

The table below provides a complete reference of all request parameters and how they affect the response.

Common query parameters (HTTP)

The following parameters are used when calling the endpoint directly via HTTP.

IdentifierType

RequestedResponseFormat

Config key to URL parameter mapping

Example Requests

HTTP

GET https://api.your-domain.com/api/items/123456/related?methods=outfits,similar_items&garment_format=detailed

JavaScript Client Library

wtSmart.extension.fashion.call("related", "items", {
  item_id: "YOUR_PRODUCT_CODE_OR_SKU",
  placement_id: "A_UUID_PROVIDED_BY_MAPP",
  response_format: "detailed",
  methods: ["outfits", "partner_outfits", "similar_items"], // should be an array, amend as required
  try_all_methods: true, // if false (the default), the methods listed are attempted until one succeeds
  onSuccess: (data) => {},
  onFailure: (err) => {},
});

Response

The response structure depends on the retrieval methods requested.

• When multiple methods are requested, each result set is returned under its corresponding key.

• When only a single method is requested, the response may contain only that section to simplify consumption.

{
  response_id: string;
  outfits?: Outfit[];
  partner_outfits?: Outfit[];
  similar_items?: {
    content_id: string;
    items: Item[] | DetailedItem[];
  };
}

{
  "response_id": "b3c1b6b0-9c2e-4a8b-9f1a-1234567890ab",
  "outfits": [
    {
      "content_id": "65dfa7",
      "items": [
        {
          "dressipi_item_id": 1322,
          "id": "REDDRESS01"
        }
      ],
      "occasion": "casual"
    }
  ],
  "partner_outfits": [
    {
      "content_id": "65dfa7",
      "items": [
        {
          "dressipi_item_id": 1322,
          "id": "REDDRESS01"
        }
      ],
      "occasion": null
    }
  ],
  "similar_items": {
    "content_id": "65dfa7",
    "items": [
      {
        "dressipi_item_id": 35122,
        "id": "602849501492"
      }
    ]
  }
}

{
  response_id: string;
  outfits: Outfit[];
}

{
  "response_id": "b3c1b6b0-9c2e-4a8b-9f1a-1234567890ab",
  "outfits": [
    {
      "content_id": "65dfa7",
      "occasion": "casual",
      "items": [
        { "dressipi_item_id": 1322, "id": "REDDRESS01" }
      ]
    }
  ]
}

Types

The following types describe the data structures returned by the related-items endpoint.

Item

Minimal representation of a returned product.

interface Item {
  id: string;
  dressipi_item_id: number;
}

DetailedItem

Extended item representation including pricing, images, availability, and metadata.

interface DetailedItem extends Item {
  name: string;
  price?: string;
  old_price?: string;
  brand_name: string;
  url: string;
  category_name?: string;
  category_id?: number;
  images: string[];
  image_url: string;
  best_model_image?: string | null;
  best_product_image?: string | '' | null;
  thumbnail_image_url?: string;
  has_outfits: boolean;
  status: 'in stock' | 'out of stock';
  style_id?: string;
}

Outfit

A grouped set of items, optionally associated with an occasion.

interface Outfit {
  content_id: string;
  occasion: string | null;
  items: Item[] | DetailedItem[];
}