---
title: "Core Concepts & Setup"
slug: "core-concepts-setup-mapp-fashion"
description: "Learn about Mapp Fashion API's authentication models, request structure, and response handling for effective integration and personalized recommendations."
tags: ["Mapp Fashion API", "Authentication Models", "Request Structure"]
updated: 2026-09-16T09:40:21Z
published: 2026-09-16T09:40:21Z
canonical: "docs.mapp.com/core-concepts-setup-mapp-fashion"
---

> ## 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.

# Core Concepts & Setup

## 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](/v1-api/apidocs/recommendation-strategy-choosing-the-right-endpoint).

---

## 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 `drsp` cookie is used internally to handle authentication
- No 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:

```http
https://your-domain.com/api/v2/{endpoint}
```

> [!NOTE]
> Note
> 
> The exact domain depends on your Mapp Fashion environment and setup.

A typical request includes:

- Your domain
- The /api path for v1, or /api/v2 for v2
- The endpoint path
- Query parameters

**Example:**

```http
https://your-domain.com/api/v2/items/outfits?id={id}&outfits_per_occasion=2
```

The v1 equivalent is https://your-domain.com/api/items/{id}/related?methods=outfits&outfits_per_occasion=2. In v2 the identifier is a query parameter rather than part of the path.

Depending 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. This is also returned when a parameter value is outside its allowed range.
- **403 – Forbidden**

A user token was supplied but could not be verified. Requests without a user token are not affected and return unpersonalized recommendations where possible.
- **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.

## Related

- [Recommendation Strategy](/recommendation-strategy-choosing-the-right-endpoint.md)
- [return outfits for a single source item](/return-outfits-for-a-single-source-item.md)