Introduction
This section explains the core technical concepts required to work with the Mapp Fashion API. It covers authentication models, request structure, context parameters, and response handling.
For guidance on selecting endpoints for specific use cases, see Recommendation Strategy.
Authentication Models
The API supports two integration approaches depending on where requests are executed.
Client-side Integration (Browser)
When used in a browser context, authentication is handled automatically via cookies set by the Mapp Fashion tracking script.
The
drspcookie is used internally to handle authenticationNo manual token handling is required
Any manually provided authentication headers will be ignored
Use this approach when API calls are triggered directly from the frontend.
Server-side Integration
In server-side scenarios, authentication requires explicit handling via a JSON Web Token (JWT). The token must be included in the x-dressipi-jwt request header.
The JWT is obtained through the authorization flow described in the Authorization section, for example via the /oauth/token endpoint.
If the token is missing or expired, endpoints will return unpersonalized recommendations where possible.
You can validate the token by checking its exp (expiration) claim.
The token must be refreshed when it expires using the authorization flow.
Use server-side integration when requests should not be exposed in the browser or when full control over authentication and request handling is required.
Request Structure
All API requests follow this general structure:
https://your-domain.com/api/{endpoint}Note
The exact domain depends on your Mapp Fashion environment and setup.
A typical request includes:
Your domain
The /api path
The endpoint path
Query parameters
Example:
https://your-domain.com/api/items/{id}/related?outfits_per_occasion=2Depending on the endpoint, additional parameters such as identifiers or context values may be required.
Context Parameters
Many endpoints support optional context parameters (for example, department, locale, or user-specific context).
Providing context is strongly recommended, as it directly affects the relevance of returned results.
Examples:
department helps ensure recommendations match the correct product category (for example, womenswear vs menswear)
locale controls which stock information is used and which language is returned (if applicable)
language can be used to localize certain feed attributes differently from price/stock locale (if supported by the feed)
If no context is provided, default catalog settings are used. This can lead to less relevant results.
Identifier Handling
Item-based endpoints depend on how identifiers are defined in your product feed and processed by Mapp Fashion.
Make sure that:
The identifier type used in requests matches your feed configuration
Identifier values are provided exactly as processed in the feed
If multiple identifier formats exist (for example sku vs product-code), align request usage with your integration conventions
If you see unexpected results or request failures, validate identifier configuration and feed processing first.
Response Overview
The API uses standard HTTP response codes:
200 – Success
The request succeeded and data is returned in the response body.
400 – Bad Request
The request is invalid. Verify parameters, authentication, and request structure.
404 – Not Found
The requested resource could not be found. Check identifiers and URLs.
422 – Unprocessable Entity
The request is syntactically correct but cannot be processed. This typically indicates a configuration or data mismatch rather than a syntax error.
Common causes include:
Unsupported or invalid identifier types
Identifier values not matching processed product feed data
Missing or incompatible parameters for the given endpoint context
500 – Server Error
An internal error occurred. Retry the request. If the issue persists, contact Technical Support.