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.
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
There is no v2 equivalent for /items/{id}, /items/{id}/complementary, /recommendations/facetted and /recommendations/themed. Use the v1 endpoints for those.
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: /items/{id}/complementary
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: /recommendations/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)
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 /items/{id}/complementary
Returns outfits or recommendations based on a set of source items. This is typically used to generate “complete the look” or basket-based recommendations.
Key considerations:
Provide multiple product identifiers in the {id} path parameter (format depends on your integration, for example comma-separated values)
Use identifier_type to match your feed setup
Use excluded_ids to avoid returning items already present in the basket
Control response size using garment_format
Use this endpoint when recommendations should be based on multiple items rather than a single product.
For basket placements you can alternatively use GET /api/v2/items/basket, which returns curated recommendations for the user profile based on the garments in the basket.
Discovery / Filtered Recommendations (PLP-like)
Use: POST /recommendations/facetted
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:
facets (filter definitions and aggregations)
page, per_page, root_event_id (pagination)
garment_format, fields
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
ean, 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.