---
title: "Using Curated Recommendations"
slug: "using-curated-recommendations"
updated: 2026-02-26T09:08:00Z
published: 2026-02-26T09:08:00Z
canonical: "docs.mapp.com/using-curated-recommendations"
---

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

# Using Curated Recommendations

## Introduction

Curated recommendations allow you to display relevant product suggestions tailored to each customer, based on their behavior and profile data.

Depending on whether product context is available, you can use two different endpoints.

---

## Prerequisites

Curated recommendations rely on behavioral and commerce data.

To achieve meaningful results, ensure the following is in place:

**Product data & model**

- A working [product feed](https://docs.mapp.com/docs/product-feed-2) is set up and processing successfully
- Product labeling is complete
- The recommendation model is enabled

**Tracking**

- [Tracking](https://docs.mapp.com/docs/mapp-fashion-tracking-setup) is implemented and sending events reliably

**Order & return data**

- Order and return data is available and processed

Without these inputs, recommendations will be limited in relevance and personalization.

---

## When to Use Which Method

Use the following guideline to choose the appropriate endpoint:

- No product context available (for example homepage or landing page)

→ Use /items/top
- Product context available (for example basket or wishlist)

→ Use /items/basket

Both endpoints use the same recommendation logic but differ in the input context.

The more context you provide (for example basket items), the more precise the recommendations become.

> [!WARNING]
> Important
> 
> Curated recommendations (for example via /items/top) default to the womenswear catalog unless the department parameter is explicitly set.
> 
> For shops with multiple departments (for example menswear and womenswear), this can lead to irrelevant results on general placements such as the homepage.
> 
> Make sure to explicitly define the department or validate whether this setup fits your use case.

---

## Without Specific Products (/items/top)

Use this endpoint when no specific product context is available, such as on a homepage or landing page.

Recommendations are based on the user profile and available behavioral data.

You can control how much data is returned using the garment_format parameter:

- retailer_ids: Returns only item identifiers (recommended for production)
- document: Returns identifiers plus selected attributes
- detailed: Returns full item data (useful for testing and debugging)

### Example Request

```http
GET /items/top?garment_format=retailer_ids&locale=DE&department=female&excluded_ids=10
```

### Example Response (simplified)

```json
{
  "event_id": "5b76c289c81285611e000071",
  "top_items": {
    "content_id": "5b76c289c81285611e000072",
    "items": [
      { "garment_id": "Q10G10NEME", "ancillary_product_code": "Q-111" },
      { "garment_id": "Q05R85NYLW", "ancillary_product_code": "Q-222" }
    ]
  }
}
```

### Selected Call Parameters

| **Parameter** | **Description** | **Example** |
| --- | --- | --- |
| garment_format | Controls the level of detail | detailed |
| locale | Defines stock and localization | DE |
| department | Filters results by department | female |
| excluded_ids | Excludes specific items | 10 |

---

## With Specific Products (/items/basket)

Use this endpoint when product context is available, such as items in a basket or wishlist.

The recommendations take the provided items into account and avoid suggesting duplicates.

The level of detail in the response can be controlled using the garment_format parameter:

- simple: Returns only basic item identifiers (recommended for production)
- detailed: Returns extended item data

### Example Request

```http
GET /items/basket?ids=SKU20001,SKU4752,SKU4003&identifier_type=sku&garment_format=simple&locale=DE&excluded_ids=SKU246803
```

### Example Response (simplified)

```json
[
  { "id": "SKU91234" },
  { "id": "SKU77441" },
  { "id": "SKU66320" }
]
```

### Selected Call Parameters

| **Parameter** | **Description** | **Example** |
| --- | --- | --- |
| ids | Item identifiers | SKU20001 |
| identifier_type | Format of identifiers | sku |
| garment_format | Controls detail level | simple |
| locale | Defines stock and localization | DE |
| excluded_ids | Excludes specific items | SKU246803 |

---

## Rendering the Results

Render the returned product list in your frontend using your preferred layout.