--- title: "Recommendation Strategy" slug: "recommendation-strategy-choosing-the-right-endpoint" description: "Choose the right API endpoint for recommendations based on product context, with guidance on parameters and integration for optimal results." tags: ["API Endpoints", "Recommendation Logic", "Product Context"] status: "update" updated: 2026-10-15T10:33:05Z published: 2026-10-15T10:33:05Z canonical: "docs.mapp.com/recommendation-strategy-choosing-the-right-endpoint" --- > ## 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. # Recommendation Strategy ## Purpose This page helps you choose the right endpoint for common recommendation placements. It explains which endpoint to use depending on whether product context is available and which parameters influence the results. For details on authentication, request structure, and parameters, see [Core Concepts & Setup](/v1-api/apidocs/core-concepts-setup-mapp-fashion). --- ## API versions Two versions of the API 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 instead of a single endpoint that takes a methods parameter. New integrations should use v2 wherever a v2 endpoint exists: - /items/{id}/related?methods=similar_items is now **/api/v2/items/similar** - /items/{id}/related?methods=outfits is now **/api/v2/items/outfits** - /items/{id}/related?methods=partner_outfits is now **/api/v2/items/partner_outfits** - /items/top is now **/api/v2/items/top** - /items/basket is now **/api/v2/items/basket** - /recommendations/facetted is now **/api/v2/facetted** There is no v2 equivalent for /items/{id} and /recommendations/themed. Use the v1 endpoints for those. > [!NOTE] > Note > > Two defaults differ between the versions. include_fashion_ids defaults to false in v2, while the v1 equivalent include_dressipi_ids defaults to true. And garment_format takes simple or detailed in v2, where simple is equivalent to the v1 value retailer_ids. A v2 call made without these parameters therefore returns fewer fields than the equivalent v1 call. --- ## Quick Decision Guide Use these questions to select the appropriate endpoint: - Do you have a single product as context (for example on a product detail page)? → Use: **/api/v2/items/similar**, **/api/v2/items/outfits** or **/api/v2/items/partner_outfits** - Do you have multiple products as context (for example in a basket or checkout)? → Use: **/api/v2/items/basket** - Do you have no product context (for example homepage or landing page)? → Use: **/api/v2/items/top** - Do you need filterable or discovery-based results (for example category or price filtering)? → Use: **/api/v2/facetted** - Do you need a predefined themed result set? → Use: **/recommendations/themed** --- ## Common Placements and Recommended Endpoints ### Homepage / Landing Page (no product context) Use: **GET /api/v2/items/top** The v1 equivalent is GET /items/top. Returns curated recommendations based on the user profile without requiring a specific product. Key parameters to consider: - department (defaults to female) - locale, language - excluded_ids - garment_format - max_items (defaults to 6) > [!WARNING] > Important > > This endpoint defaults to department=female and currently returns recommendations from the womenswear catalog unless a different department is explicitly specified. > > For shops with multiple departments (for example menswear and womenswear), this can lead to irrelevant results on general placements such as the homepage. > > In such cases, you should explicitly control the department parameter or validate whether this endpoint is suitable for your use case. --- ### Product Detail Page (PDP) (single product context) Use: **GET /api/v2/items/similar**, **GET /api/v2/items/outfits** or **GET /api/v2/items/partner_outfits** Each of these returns one type of recommendation. The v1 equivalent is a single call to GET /items/{id}/related with the methods parameter. Returns similar items, outfits, or partner outfits based on a single source product. Key parameters to consider: - id (the product identifier, passed as a parameter rather than in the URL) - identifier_type (for example product-code, sku) - exclude_source_garment, excluded_ids (excluded_ids on /similar only) - max_items, outfits_per_occasion (outfits_per_occasion on /outfits only) - max_reduced_by - locale, language - garment_format Use this endpoint when recommendations should be directly related to the currently viewed product. --- ### Basket / Checkout / Wishlist (multiple product context) Use: **GET /api/v2/items/basket** The v1 equivalent is GET /items/basket. Returns curated recommendations for the user profile, like /api/v2/items/top, taking the garments in the basket into account. It does not build outfits and does not return items similar to the basket garments. The basket garments themselves are excluded from the results. Key parameters to consider: - ids (the garments in the basket as a comma-separated list; the department is taken from them) - identifier_type (for example product-code, sku, gtin) - excluded_ids (additional items to exclude; the basket garments are excluded automatically) - max_items (defaults to 6), max_reduced_by - locale, language - garment_format Use this endpoint when recommendations should take the current basket into account. If the basket is empty or none of the identifiers can be resolved, recommendations are still returned. --- ### Discovery / Filtered Recommendations (PLP-like) Use: **POST /api/v2/facetted** The v1 equivalent is POST /recommendations/facetted. Compared to v1, filters are passed as an object keyed by filter name, min_price and max_price are available, and canonical_only, fields and device_type are not supported. Returns recommended items for a user with support for filtering and aggregations (facets). Typical use cases: - Category or product listing pages with filters - Discovery experiences with dynamic refinement Supported filtering includes: - Category, brand, occasion - Features and attributes - Price and discount ranges - Store availability (if provided in the feed) Key parameters: - filters, aggregations (request body: filter definitions and facets to count) - page, per_page, root_event_id (pagination) - department (defaults to female) - garment_format - locale, language --- ### Themed Recommendations Use: **GET /recommendations/themed** Returns recommendations based on a predefined theme configured as part of your Mapp Fashion setup. Typical use cases: - Predefined merchandising concepts (for example seasonal or campaign-driven selections) Key parameters: - theme (required) - count - device_type - locale, language - garment_format, fields --- ## Supporting Endpoint: Product Data Retrieval ### Get product details Use: **GET /items/{id}** Fetches detailed information about a single product. Typical use cases: - Enriching product detail pages with additional attributes - Debugging identifier mapping and feed integration - Validating localized product data Key parameters: - identifier_type - fields - locale, language This endpoint does not return recommendations but provides product-level data used in recommendation scenarios. --- ## Core Considerations ### Identifier Handling Item-based endpoints rely on interpreting product identifiers via the identifier_type parameter (default: product-code). Supported types include: - product-code - sku - gtin - fashion-id (called dressipi-id in v1) - ancillary-product-code (v1 only) The available identifier types and valid values depend on your product feed configuration. There is no fallback logic for partial matches: an identifier must match completely. ancillary-product-code is an additional, optional product code that is checked against the product code column for a complete match. If requests fail or return unexpected results, verify: - The identifier type matches your feed setup - The identifier value matches the processed feed exactly --- ### Context Parameters Parameters such as department, locale, and language influence which items are returned and how attributes are localized. If no context is provided, default catalog settings are used. For shops with multiple departments, providing explicit context is recommended to ensure relevant results. --- ### Output Format Several endpoints support controlling response size using garment_format: - simple → identifiers only (recommended for production). This is the v2 name for the v1 value retailer_ids - detailed → full product data (useful for testing and debugging) - document → identifiers plus selected attributes. v1 only In v1 you can use the fields parameter to request specific attributes where supported. v2 has no equivalent: the set of attributes returned for detailed is fixed and depends on the endpoint and the product feed. --- ## Scope and Assumptions This page is based on the publicly available Mapp Fashion API endpoints and describes common integration patterns. Actual behavior and suitability may depend on: - Product feed structure and completeness - Tracking implementation - Configured recommendation logic and business rules Validate your setup and test endpoints in your specific environment to ensure expected results. ## Related - [return curated partner outfits for a single source item](/return-curated-partner-outfits-for-a-single-source-item.md) - [return similar items for a single source item](/return-similar-items-for-a-single-source-item.md) - [return outfits for a single source item](/return-outfits-for-a-single-source-item.md)