> ## 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 top curated recommendations for a user based on their basket items > Returns personalized curated recommendations for a user, like `/items/top`. It does not return items similar to the garments in the basket. The department is taken from the garments in the basket, and these garments are excluded from the recommendations. The basket can be empty. **v2 equivalent:** `/api/v2/items/basket`. New integrations should use it. ## OpenAPI ````json GET /items/basket { "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/basket": { "get": { "tags": [ "Items" ], "summary": "return top curated recommendations for a user based on their basket items", "description": "Returns personalized curated recommendations for a user, like `/items/top`. It does not return items similar to the garments in the basket. The department is taken from the garments in the basket, and these garments are excluded from the recommendations. The basket can be empty.\n\n**v2 equivalent:** `/api/v2/items/basket`. New integrations should use it.\n", "operationId": "getItemsBasket", "parameters": [ { "name": "ids", "in": "query", "description": "List of garment identifiers representing the user's basket, for example `ids=A,B`. Identifiers that cannot be resolved are ignored. The basket garments 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, recommendations are still returned.\n", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "excluded_ids", "in": "query", "description": "List of garment identifiers to be excluded from the recommendations.\n", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "identifier_type", "in": "query", "description": "The type of garment identifiers provided in `ids` and `excluded_ids`.\n\nThere is no fallback logic for partial matches: an identifier must match completely, and the first match is used for the response.\n\nIn general, product-code is the style + color identifier from your product data, sku is the variant identifier (style, color and size) and gtin is the barcode, for example EAN-13 or UPC.\n", "schema": { "enum": [ "product-code", "sku", "dressipi-id", "gtin" ], "type": "string" } }, { "name": "max_items", "in": "query", "description": "The desired number of recommended items to return.\n", "schema": { "type": "integer", "format": "int32" } }, { "name": "max_reduced_by", "in": "query", "description": "The maximum price reduction (in percent) of any returned item. Requires that discount data is shared with the API.\n", "schema": { "maximum": 100, "minimum": 1, "type": "integer", "format": "int32" } }, { "name": "sort", "in": "query", "description": "The attribute to sort results by. Currently only 'price' is supported.\n", "schema": { "enum": [ "price" ], "type": "string" } }, { "name": "direction", "in": "query", "description": "The direction to sort results by.\n", "schema": { "enum": [ "asc", "desc" ], "type": "string", "default": "desc" } }, { "name": "garment_format", "in": "query", "description": "The desired response format. If 'simple', only basic garment identifiers are returned.\nIf 'detailed', more comprehensive garment metadata is included.\n", "schema": { "enum": [ "simple", "detailed" ], "type": "string", "default": "simple" } }, { "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": "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": "include_user_data", "in": "query", "description": "If true, user information will be included in the response where applicable\n", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Information about the curated recommendations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasketRecommendationsResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidParams" }, "403": { "$ref": "#/components/responses/InvalidJwt" }, "404": { "description": "No recommender is available for this partner", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The recommendation service reported an error. The response contains its message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "schemas": { "BasketRecommendationsResponse": { "required": [ "event_id", "recommendations" ], "type": "object", "properties": { "event_id": { "type": "string", "description": "The unique event ID for tracking purposes" }, "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" }, "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/BareGarment" }, "description": "The recommended items for the current basket" }, "garment_data": { "type": "array", "items": { "type": "object" }, "description": "Metadata for the garments in the response" }, "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." }, "user": { "$ref": "#/components/schemas/User" } }, "description": "The basket recommendations endpoint returns curated recommendations for a user profile\nbased on the garments in their basket (which can be empty).\n\nThis endpoint provides personalized item recommendations based on the user's profile\nand preferences.\n", "example": { "event_id": "1234567890abcdef", "currency": "GBP", "recommendations": [ { "garment_id": "Q10G10NEME", "raw_garment_id": 4532078, "ancillary_product_code": "Q-111" }, { "garment_id": "Q05R85NYLW", "raw_garment_id": 4532040, "ancillary_product_code": "Q-222" } ], "garment_data": [], "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" ] } }, "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" } } } } ````