> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scentxp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Recommendations

## Personalized recommendations

Generic "customers also bought" recommendations don't work for fragrance — two popular perfumes can smell completely different. A customer who loves a woody ambery will not appreciate a fresh citrus, regardless of how many other people bought it.

WikiParfum generates recommendations based on **olfactive affinity**: ingredient composition, family relationships, and structural similarity. The result is suggestions that genuinely smell like something the user would enjoy — driving higher conversion and trust in the recommendation.

### The business impact

* **Higher conversion** — trust in the recommendation drives purchase
* **Increased average order value** — users explore and add complementary products
* **Stronger loyalty** — personalized experiences generate return visits (most users return within 30 days)
* **Better cross-sell** — suggest products based on what customers actually like, not just what's popular

### What you can build

* **"If you like this" carousels** on product pages
* **Cross-sell and upsell modules** based on olfactive proximity
* **Scan-to-recommend** experiences using EAN barcodes
* **Personalized homepages** based on browsing history
* **Catalog-restricted recommendations** scoped to a retailer's assortment

## Recommend similar perfumes

Given one or more perfumes the user likes, get similar fragrances ranked by olfactive proximity.

<CodeGroup>
  ```graphql Query theme={null}
  query RecommendedPerfumes {
    recommendedPerfumes(search: {
      perfumes: "424,1"
      lang: "EN"
      page: "0,10"
    }) {
      id
      name
      recoValue
      brand {
        name
      }
      family {
        name
        color
      }
      image {
        urls {
          low
          mid
        }
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumes": [
        {
          "id": "734",
          "name": "HYPNOTIC POISON",
          "recoValue": "0.9444",
          "brand": {
            "name": "Dior"
          },
          "family": {
            "name": "AMBERY (ORIENTAL)",
            "color": "#B41F24"
          },
          "image": {
            "urls": {
              "low": "https://api-assets.wikiparfum.com/_resized/bcc0afq0ryujbeeg4473aem507yb6ghefxu5ipfyo3ubdii949ujh5flcmej-w100-q85.jpg",
              "mid": "https://api-assets.wikiparfum.com/_resized/bcc0afq0ryujbeeg4473aem507yb6ghefxu5ipfyo3ubdii949ujh5flcmej-w250-q85.jpg"
            }
          }
        },
        {
          "id": "7684",
          "name": "TOY 2",
          "recoValue": "0.9291",
          "brand": {
            "name": "Moschino"
          },
          "family": {
            "name": "FLORAL",
            "color": "#E2839A"
          },
          "image": {
            "urls": {
              "low": "https://api-assets.wikiparfum.com/_resized/5b84tfidpdno2ccieq2zomtwxhg750zo18jw7tclq8li7ixw0x0mhxb9jgoy-w100-q85.jpg",
              "mid": "https://api-assets.wikiparfum.com/_resized/5b84tfidpdno2ccieq2zomtwxhg750zo18jw7tclq8li7ixw0x0mhxb9jgoy-w250-q85.jpg"
            }
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

### Match score

Each recommendation includes a `recoValue` field: a similarity score between `0` and `1` representing how closely the recommended perfume matches the user's profile. Results are sorted by this score in descending order, so the first result is always the best match.

The score is computed from multiple olfactive dimensions including ingredient overlap, fragrance family proximity, and intensity similarity. You can convert it to a percentage for display purposes (e.g., `0.87` = 87% match).

| Value range | Interpretation    |
| ----------- | ----------------- |
| `0.8 - 1.0` | Very strong match |
| `0.6 - 0.8` | Good match        |
| `0.3 - 0.6` | Moderate match    |

### Recommend by EAN

Use EAN barcodes as input — ideal for scan-based or POS-integrated experiences where you have barcodes but not WikiParfum IDs.

<CodeGroup>
  ```graphql Query theme={null}
  query RecommendByEAN {
    recommendedPerfumes(search: {
      perfumeEans: "8411061994351,0085715166067"
      lang: "EN"
      page: "0,10"
    }) {
      id
      name
      brand {
        name
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumes": [
        {
          "id": "7684",
          "name": "TOY 2",
          "brand": {
            "name": "Moschino"
          }
        },
        {
          "id": "734",
          "name": "HYPNOTIC POISON",
          "brand": {
            "name": "Dior"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

## User-scoped recommendations

Pass a `userId` to incorporate the user's interaction history into the ranking. Over time, recommendations become increasingly aligned with each user's evolving taste profile — without requiring explicit questionnaires or profile setup.

<CodeGroup>
  ```graphql Query theme={null}
  query UserRecommendations {
    recommendedPerfumes(
      search: {
        perfumes: "424"
        lang: "EN"
        page: "0,10"
      }
      userId: "user-abc-123"
    ) {
      id
      name
      brand {
        name
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumes": [
        {
          "id": "734",
          "name": "HYPNOTIC POISON",
          "brand": {
            "name": "Dior"
          }
        },
        {
          "id": "36141",
          "name": "GUCCI GUILTY ABSOLU DE PARFUM POUR FEMME",
          "brand": {
            "name": "Gucci"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

## Scoping to a catalog

### Custom recommendation rules

Use `customRecommendation` to control which brands or perfumes appear in results. This is essential for retailers who need recommendations limited to their own assortment, or brands that want to exclude competitors.

<CodeGroup>
  ```graphql Query theme={null}
  query CustomRecommendations {
    recommendedPerfumes(search: {
      perfumes: "424"
      lang: "EN"
      page: "0,10"
      customRecommendation: {
        enabled: true
        excludedBrands: [42, 87]
        includedBrands: [10, 25, 33]
        excludedPerfumes: [1]
      }
    }) {
      id
      name
      brand {
        name
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumes": [
        {
          "id": "5807",
          "name": "AMBRE SULTAN",
          "brand": {
            "name": "Serge Lutens"
          }
        },
        {
          "id": "3925",
          "name": "RAHÄT LOUKOUM",
          "brand": {
            "name": "Serge Lutens"
          }
        }
      ]
    }
  }
  ```
</CodeGroup>

| Field              | Description                            |
| ------------------ | -------------------------------------- |
| `excludedBrands`   | Brand IDs to exclude from results      |
| `includedBrands`   | Only return perfumes from these brands |
| `excludedPerfumes` | Specific perfume IDs to exclude        |
| `includedPerfumes` | Specific perfume IDs to include        |

### Filtering results

Recommendations can be further narrowed using standard filters — for example, limiting to a specific gender or market segment. See [Filtering & Pagination](/wikiparfum-api/features/filtering) for all available filter options.

<CodeGroup>
  ```graphql Query theme={null}
  query FilteredRecommendations {
    recommendedPerfumes(search: {
      perfumes: "424"
      lang: "EN"
      page: "0,10"
      filters: {
        gender: "F"
        classification: "prestige"
      }
    }) {
      id
      name
      gender
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumes": [
        {
          "id": "16280",
          "name": "VERY GOOD GIRL",
          "gender": "F"
        }
      ]
    }
  }
  ```
</CodeGroup>

### Price-based filtering and sorting

If your catalog includes product prices via the [Product Feed](/catalog-integration/product-feed), you can filter recommendations by price range and sort by price.

<CodeGroup>
  ```graphql Query theme={null}
  query PriceFilteredRecommendations {
    recommendedPerfumes(search: {
      perfumes: "424"
      lang: "EN"
      page: "0,10"
      order_by: "customerPrice-asc"
      filters: {
        customerPriceRange: "10,100"
      }
    }) {
      id
      name
      brand {
        name
      }
    }
  }
  ```
</CodeGroup>

| Parameter                        | Description                                   |
| -------------------------------- | --------------------------------------------- |
| `customerPriceRange: "min,max"`  | Only return perfumes priced within this range |
| `order_by: "customerPrice-asc"`  | Sort by price, lowest first                   |
| `order_by: "customerPrice-desc"` | Sort by price, highest first                  |

<Note>
  These options require the `price` column in your [Product Feed](/catalog-integration/feed-format). Perfumes without a price in your catalog are excluded when filtering, and placed last when sorting.
</Note>

## Ingredient recommendations

Given a set of ingredients the user enjoys, surface other ingredients they might like. This powers ingredient-based exploration flows where users progressively build an olfactive profile.

<CodeGroup>
  ```graphql Query theme={null}
  query RecommendedIngredients {
    recommendIngredients(search: {
      ingredients: "710,42"
      lang: "EN"
      page: "0,10"
    }) {
      ingredients {
        id
        name
        family {
          name
        }
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendIngredients": {
        "ingredients": [
          {
            "id": "9",
            "name": "Aldehyde",
            "family": {
              "name": "ALDEHYDIC"
            }
          },
          {
            "id": "12",
            "name": "Allspice",
            "family": {
              "name": "SPICY"
            }
          }
        ]
      }
    }
  }
  ```
</CodeGroup>

## Perfumer recommendations

Surface the perfumer whose creative style best matches the user's taste — based on the perfumes they enjoy.

<CodeGroup>
  ```graphql Query theme={null}
  query RecommendedPerfumist {
    recommendedPerfumist(
      perfumes: ["100", "200", "300"]
      lang: "EN"
    ) {
      id
      name
      bio
      house
      image1 {
        urls {
          low
          mid
        }
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumist": {
        "id": "82",
        "name": "Jacques Polge",
        "bio": "Jacques Polge is a renowned French perfumer, known for his pivotal role at Chanel, where he was the exclusive nose from 1978 to 2015. Trained at the Givaudan perfumery school, he began his career in the 1960s, working in particular for Roure Bertrand Dupont, a composition house where he honed his art.\n\nHis arrival at Chanel marked a turning point in the company's history. For over 35 years, Jacques Polge brilliantly reinterpreted the brand's olfactory codes, while at the same time innovating. He was responsible for such iconic fragrances as Coco (1984), Égoïste (1990), Allure (1996), Coco Mademoiselle (2001) and Chance (2002).\n\nHe also modernised the house's classics, such as N°5, by creating versions like Eau Première. Under his leadership, Chanel continues to combine timeless elegance with olfactory innovation.\n\nJacques Polge is renowned for his precise and refined style, based on a balance of raw materials and a distinctive olfactory signature, as well as for his ability to combine tradition and modernity. When he stepped down in 2015, he passed the torch to his son, Olivier Polge, himself a talented perfumer.",
        "house": "Chanel",
        "image1": {
          "urls": {
            "low": "https://api-assets.wikiparfum.com/_resized/0ma3w8lcqdo8v0tfabfxlb094uisluias55i520u2189b4yswys8b8f6in9o-w100-q85.jpg",
            "mid": "https://api-assets.wikiparfum.com/_resized/0ma3w8lcqdo8v0tfabfxlb094uisluias55i520u2189b4yswys8b8f6in9o-w500-q85.jpg"
          }
        }
      }
    }
  }
  ```
</CodeGroup>

This enables "meet your perfumer" modules that connect users to the creators behind their favorite fragrances.