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
/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
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)
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.