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.
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: /items/{id}/related
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: /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 /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 and fields
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 /items/{id}/related
Returns similar items, outfits, or partner outfits based on a single source product.
Key parameters to consider:
methods (for example: similar_items, outfits, partner_outfits)
identifier_type (for example product-code, sku)
sku_refinement (when using identifier_type=sku)
exclude_source_garment, excluded_ids
max_similar_items, outfits_per_occasion
locale, language
garment_format and fields
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.
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
dressipi-id, ancillary-product-code
The available identifier types and valid values depend on your product feed configuration.
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:
retailer_ids → identifiers only (recommended for production)
document → identifiers plus selected attributes
detailed → full product data (useful for testing and debugging)
Use the fields parameter to request specific attributes where supported.
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.