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 is set up and processing successfully

• Product labeling is complete

• The recommendation model is enabled

Tracking

• Tracking 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.

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

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

Example Response (simplified)

{
  "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

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

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

Example Response (simplified)

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

Selected Call Parameters

Rendering the Results

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