> ## 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. # return outfits or similar items for a single source item > Fetches either similar items (items which are related to the source item by common features) or outfits (items which as a set complement the source item).' This is the api equivalent of the outfits widget. **v2 equivalent:** this endpoint's methods are available as separate v2 endpoints: `/api/v2/items/similar`, `/api/v2/items/outfits` and `/api/v2/items/partner_outfits`. New integrations should use those. ## OpenAPI ````json GET /items/{id}/related { "openapi": "3.0.4", "info": { "title": "Mapp Fashion API", "description": "Mapp Fashion recommendation API.\n\n**Host:** there is no shared API host. A dedicated host is configured per partner and supplied during onboarding. All paths below are relative to that host.\n\nTwo versions are available in parallel. **v1** (`/api/...`) covers the established endpoints and is fully maintained, with no deprecation planned. **v2** (`/api/v2/...`) standardizes the inputs and provides one endpoint per recommendation type. New integrations should use v2 wherever a v2 endpoint exists. See Recommendation Strategy for which endpoint to use when.\n", "version": "13" }, "servers": [ { "url": "/api" } ], "security": [ { "api_key": [] }, { "api_key": [], "user_token": [] } ], "tags": [ { "name": "Items", "description": "Operations for retrieving recommendations or items related to one or more seed items" }, { "name": "Items (v2)", "description": "v2: one endpoint per recommendation type, identifiers passed as parameters" }, { "name": "Recommendations", "description": "Operations about recommendations" }, { "name": "Recommendations (v2)", "description": "v2: facetted recommendations in the v2 response format" }, { "name": "Authorization", "description": "Operations for obtaining or refreshing JWTs" } ], "paths": { "/items/{id}/related": { "get": { "tags": [ "Items" ], "summary": "return outfits or similar items for a single source item", "description": "Fetches either similar items (items which are related to the source item by common features)\nor outfits (items which as a set complement the source item).'\n\nThis is the api equivalent of the outfits widget.\n\n\n**v2 equivalent:** this endpoint's methods are available as separate v2 endpoints: `/api/v2/items/similar`, `/api/v2/items/outfits` and `/api/v2/items/partner_outfits`. New integrations should use those.\n", "operationId": "getItemsIdRelated", "parameters": [ { "name": "id", "in": "path", "description": "An identifier for the source item. The interpretation of this item is controlled by the `identifier_type` parameter", "required": true, "schema": { "type": "string" } }, { "name": "methods", "in": "query", "description": "The methods through which related items should be generated. These are attempted in order.\n\nThe `partner_outfits` method is only available if Mapp Fashion has been provided with curated outfit data for the item\n", "schema": { "type": "array", "items": { "enum": [ "similar_items", "outfits", "partner_outfits" ], "type": "string" }, "default": [ "outfits", "similar_items" ] } }, { "name": "try_all_methods", "in": "query", "description": "If false (the default), the methods listed are attempted until one succeeds and only results for that method are returned.\n\nIf true, results for all successful methods are returned\n", "schema": { "type": "boolean" } }, { "name": "locale", "in": "query", "description": "A locale parameter describing what stock information to use and what language to return text in (if applicable). This parameter will only\nfunction if the corresponding information is in your product data & processed accordingly. If stock local and UI language are not the same,\nspecify the language parameter in addition to this one.\n", "schema": { "type": "string" } }, { "name": "language", "in": "query", "description": "Allows you to specify a locale used for product attributes such as product name that should be localized using a different locale to price &\nstock information. This parameter will only function if the corresponding information is in your product data & processed accordingly.\n", "schema": { "type": "string" } }, { "name": "exclude_source_garment", "in": "query", "description": "Whether to exclude the source item from any returned outfits or not\n", "schema": { "type": "boolean", "default": true } }, { "name": "outfits_per_occasion", "in": "query", "description": "The number of outfits to attempt to return *per occasion*. In the case of a single occasion garment, this\nlimit is doubled internally. If fewer outfits are available, as many as possible are returned\n", "schema": { "type": "integer", "format": "int32", "default": 2 } }, { "name": "max_similar_items", "in": "query", "description": "The maximum number of similar items to return.\n", "schema": { "type": "integer", "format": "int32", "default": 6 } }, { "name": "stores", "in": "query", "description": "**Deprecated.** This parameter still returns data, but the logic behind it is no longer maintained and it has no v2 equivalent. Do not rely on it for new integrations.\n\nList of stores to filter recommendations by. An item must be available in at least one of the specified stores in order\nto be returned.\n\nThis requires that per-store availability data is shared with Mapp Fashion\n", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "garment_format", "in": "query", "description": "The desired response format.\n\nThe response includes a description of the outfits / similar items but no data on the items themselves: since these may be repeated within the response, garment data is provided separately in the response.\n\nThe `detailed` format includes the most amount of item metadata (name, description, price etc).\n\nThe `document` format only includes item identifiers, and if requested Mapp Fashion generated information about the item, such as predicted size.\n\nThe `retailer_ids` format only returns the item identifiers.\n", "schema": { "enum": [ "detailed", "document", "retailer_ids" ], "type": "string", "default": "retailer_ids" } }, { "name": "identifier_type", "in": "query", "description": "How Mapp Fashion should interpret the item id. Not all of these may be available, depending on the information in your product data and how it is processed. Contact Mapp Fashion for examples of these types for your specific integration.\n\nIn general\n\n- product-code is the style + color identifier from your product data\n- sku is the variant identifier (style, color and size)\n- gtin is the barcode, for example EAN-13 or UPC\n\nThere is no fallback logic for partial matches: an identifier must match completely, and the first match is used for the response.\n\n`ancillary-product-code` is an additional, optional product code. When used, it is checked against the product code column for a complete match.\n", "schema": { "enum": [ "dressipi-id", "gtin", "product-code", "sku", "ancillary-product-code" ], "type": "string", "default": "product-code" } }, { "name": "pretty", "in": "query", "description": "If true, pretty print JSON output. This increases response size and should usually be off in production environments\n", "schema": { "type": "boolean", "default": false } }, { "name": "include_dressipi_ids", "in": "query", "description": "Controls whether Mapp Fashion garment ids (raw_garment_id) are included in response\n", "schema": { "type": "boolean", "default": true } }, { "name": "fields", "in": "query", "description": "**Deprecated.** This parameter still returns data, but the logic behind it is no longer maintained and it has no v2 equivalent. Do not rely on it for new integrations.\n\nA list of garment attributes to fetch. Only supported for garment_format=document or detailed. Retailer specific custom fields are named `x-` and may be requested in addition to the values listed here - contact Mapp Fashion for details", "schema": { "type": "array", "items": { "enum": [ "size", "why", "verdict", "recommendedness", "features", "occasions", "garment_category_id", "owned", "department", "eans" ], "type": "string" } } }, { "name": "excluded_ids", "in": "query", "description": "List of product identifiers to be excluded from the results.\nThe interpretation of this item is controlled by the `identifier_type` parameter\n", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "include_user_data", "in": "query", "description": "Include information about the user in the response (if known)\n", "schema": { "type": "boolean" } }, { "name": "max_reduced_by", "in": "query", "description": "The maximum price reduction (in percent) of any returned item\n", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Information about the related garments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedItemsResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidParams" }, "403": { "$ref": "#/components/responses/InvalidJwt" }, "422": { "description": "garment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "RelatedItemsResponse": { "required": [ "event_id", "source", "outfits", "partner_outfits", "similar_items" ], "type": "object", "properties": { "event_id": { "type": "string", "description": "An event id. This should be used when posting events relating to this dataset.", "example": "5a621005c2c9adc12e1192b7" }, "currency": { "type": "string", "description": "The currency the prices in this response are expressed in, resolved from the requested locale (the default currency if no locale is given). Null if your product data contains no currency", "nullable": true, "example": "GBP" }, "source": { "$ref": "#/components/schemas/BareGarment" }, "reparentable": { "type": "boolean", "description": "If true, the eventid should be posted to /events/{id}/reparent" }, "garment_data": { "type": "array", "items": { "type": "object" }, "description": "Extra data about the garments in the response. Only present for `detailed` and `document` response formats. Do not rely on this for the correct ordering of results (use the similar_items or outfits key as appropriate)" }, "available_skus": { "type": "array", "items": { "$ref": "#/components/schemas/AvailableSkus" }, "description": "The variant SKUs of the recommended items that are still in stock, one entry per item. An empty array when none are known.\n\nOnly reliable if the variant IDs are maintained in the Product Catalog and the products have their real product images from the first import on. Products imported with placeholder images or dummy URLs can receive SKUs of other products." }, "outfits": { "type": "array", "items": { "$ref": "#/components/schemas/Outfit" }, "description": "The outfits found containing the source item (if any)" }, "partner_outfits": { "type": "array", "items": { "$ref": "#/components/schemas/Outfit" }, "description": "The partner_outfits found containing the source item (if any). `template_id` will always be `partner_outfit` for these outfits" }, "similar_items": { "$ref": "#/components/schemas/SimilarItems" }, "user": { "$ref": "#/components/schemas/User" } }, "description": "Fetches either similar items (items which are related to the source item by common features)\nor outfits (items which as a set complement the source item).'\n\nThis is the api equivalent of the outfits widget.\n", "example": { "event_id": "57fe1f6f44b3a71e07000018", "currency": "GBP", "reparentable": false, "outfits": [ { "content_id": "5a586e000e345073dc005d80", "garment_id": "EH602-cobalt", "items": [ { "garment_id": "EH602-cobalt", "raw_garment_id": 4086212 }, { "garment_id": "BS691-silver", "raw_garment_id": 4407754 }, { "garment_id": "JA112-silver", "raw_garment_id": 4407761 }, { "garment_id": "JA025-grey", "raw_garment_id": 4412237 } ], "occasion": "occasion", "template_id": "gcHg-zQI", "saved": true }, { "content_id": "5a586e040e345073d9006d74", "garment_id": "EH602-cobalt", "items": [ { "garment_id": "XD007-ivory", "raw_garment_id": 4406224 }, { "garment_id": "EH602-cobalt", "raw_garment_id": 4086212 }, { "garment_id": "BL806-black", "raw_garment_id": 4429859 }, { "garment_id": "JA654-black", "raw_garment_id": 4428429 } ], "occasion": "occasion", "template_id": "MSnOF6ML", "saved": false } ], "similar_items": { "content_id": "5a586e040e345073d9006d75", "items": [ { "garment_id": "XQ164-blue", "raw_garment_id": 4415997, "ancillary_product_code": "XB-111" }, { "garment_id": "TK866-purple", "raw_garment_id": 4126091, "ancillary_product_code": "TP-222" }, { "garment_id": "FM799-ultraviolet", "raw_garment_id": 4167941, "ancillary_product_code": "FU-333" }, { "garment_id": "GL075-cobalt", "raw_garment_id": 4298227, "ancillary_product_code": "GC-444" }, { "garment_id": "MP208-zebra-print", "raw_garment_id": 4125958, "ancillary_product_code": "MZP-555" }, { "garment_id": "GL038-navy-spot", "raw_garment_id": 4421750, "ancillary_product_code": "GLS-666" } ] }, "partner_outfits": [], "garment_data": [], "source": { "garment_id": "EH602-cobalt", "raw_garment_id": 4086212, "ancillary_product_code": "EC-123" }, "user": { "style_quiz_complete": true, "first_name": "Jane" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "A human readable error message" } } } }, "description": "Generic error object" }, "BareGarment": { "required": [ "garment_id" ], "type": "object", "properties": { "garment_id": { "type": "string", "description": "The item identifier. In v2, it uses the same identifier type as the request (`identifier_type`), by default the product code. In v1, the type of identifier depends on the request's `garment_format`", "example": "ABC-123" }, "raw_garment_id": { "type": "integer", "description": "The internal Mapp Fashion id for the garment. This may be omitted depending on `garment_format`", "format": "int32", "example": 123456 }, "product_id": { "type": "string", "description": "The product level identifier the item belongs to (Product ID in the Product Catalog), grouping all its colors and sizes. Omitted if your product data contains no Product ID", "example": "TS30165" }, "ancillary_product_code": { "type": "string", "description": "An alternative identifier to identify the product, hidden when not provided in your product data", "example": "A1B2C3" } } }, "AvailableSkus": { "required": [ "garment_id", "skus" ], "type": "object", "properties": { "garment_id": { "type": "string", "description": "The item the SKUs belong to, as returned in `garment_id`" }, "skus": { "type": "array", "items": { "type": "string" }, "description": "The variant SKUs of the item that are still in stock" } }, "description": "The in-stock variant SKUs of one recommended item.", "example": { "garment_id": "TS30165CHARCOALHB", "skus": [ "TS30165CHARCOALHB-S", "TS30165CHARCOALHB-M" ] } }, "Outfit": { "required": [ "content_id", "garment_id", "template_id", "occasion", "items", "saved" ], "type": "object", "properties": { "content_id": { "type": "string", "description": "An opaque identifier identifying this section of the response. This should be used when posting posting events relating to an item in this outfit.", "example": "5a621005c2c9adc12e1192b7" }, "garment_id": { "type": "string", "description": "The garment id for which the outfit was constructed", "example": "ABC-123" }, "raw_garment_id": { "type": "integer", "description": "The internal Mapp Fashion id for the main garment. This may be omitted depending on `garment_format`", "format": "int32", "example": 123456 }, "template_id": { "type": "string", "description": "A string identifying the template from which the outfit was constructed", "example": "xyzAbc" }, "occasion": { "type": "string", "description": "The occasion for this outfit. May be null", "nullable": true, "example": "casual" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BareGarment" }, "description": "The items making up the outfit" }, "id": { "type": "string", "description": "The saved outfit id" }, "saved": { "type": "boolean", "description": "Indicate whether the user saved the outfit or not", "example": true } }, "description": "An outfit built around a source garment: the occasion it was built for, the template used and the items it consists of." }, "SimilarItems": { "required": [ "content_id", "items" ], "type": "object", "properties": { "content_id": { "type": "string", "description": "An opaque identifier identifying this section of the response. This should be used when posting events relating to an item in this outfit.", "example": "5a621005c2c9adc12e1192b7" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/BareGarment" }, "description": "The similiar items" } } }, "User": { "type": "object", "properties": { "style_quiz_complete": { "type": "boolean", "description": "Whether the user has completed the Mapp Fashion signup quiz" }, "first_name": { "type": "string", "description": "The user's first name, if they have supplied it" } } } }, "responses": { "InvalidParams": { "description": "One or more parameter values are invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InvalidJwt": { "description": "Invalid JWT: a user token was supplied but could not be verified. Requests without a user token are not affected - they return non-personalized results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "An internal error occurred. Retry the request. If the issue persists, contact Technical Support", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "securitySchemes": { "api_key": { "type": "apiKey", "name": "x-api-key", "in": "header" }, "user_token": { "type": "apiKey", "description": "The JWT for the user. Optional: requests without a user token return non-personalized results. The header name is unchanged for backwards compatibility.", "name": "x-dressipi-jwt", "in": "header" } } } } ````