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

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

query RecommendedPerfumes {
  recommendedPerfumes(search: {
    perfumes: "424,1"
    lang: "EN"
    page: "0,10"
  }) {
    id
    name
    recoValue
    brand {
      name
    }
    family {
      name
      color
    }
    image {
      urls {
        low
        mid
      }
    }
  }
}

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

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

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

query RecommendByEAN {
  recommendedPerfumes(search: {
    perfumeEans: "8411061994351,0085715166067"
    lang: "EN"
    page: "0,10"
  }) {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "7684",
        "name": "TOY 2",
        "brand": {
          "name": "Moschino"
        }
      },
      {
        "id": "734",
        "name": "HYPNOTIC POISON",
        "brand": {
          "name": "Dior"
        }
      }
    ]
  }
}

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.

query UserRecommendations {
  recommendedPerfumes(
    search: {
      perfumes: "424"
      lang: "EN"
      page: "0,10"
    }
    userId: "user-abc-123"
  ) {
    id
    name
    brand {
      name
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "734",
        "name": "HYPNOTIC POISON",
        "brand": {
          "name": "Dior"
        }
      },
      {
        "id": "36141",
        "name": "GUCCI GUILTY ABSOLU DE PARFUM POUR FEMME",
        "brand": {
          "name": "Gucci"
        }
      }
    ]
  }
}

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.

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
    }
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "5807",
        "name": "AMBRE SULTAN",
        "brand": {
          "name": "Serge Lutens"
        }
      },
      {
        "id": "3925",
        "name": "RAHÄT LOUKOUM",
        "brand": {
          "name": "Serge Lutens"
        }
      }
    ]
  }
}

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 for all available filter options.

query FilteredRecommendations {
  recommendedPerfumes(search: {
    perfumes: "424"
    lang: "EN"
    page: "0,10"
    filters: {
      gender: "F"
      classification: "prestige"
    }
  }) {
    id
    name
    gender
  }
}

{
  "data": {
    "recommendedPerfumes": [
      {
        "id": "16280",
        "name": "VERY GOOD GIRL",
        "gender": "F"
      }
    ]
  }
}

Price-based filtering and sorting

If your catalog includes product prices via the Product Feed, you can filter recommendations by price range and sort by price.

query PriceFilteredRecommendations {
  recommendedPerfumes(search: {
    perfumes: "424"
    lang: "EN"
    page: "0,10"
    order_by: "customerPrice-asc"
    filters: {
      customerPriceRange: "10,100"
    }
  }) {
    id
    name
    brand {
      name
    }
  }
}

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

These options require the price column in your Product Feed. Perfumes without a price in your catalog are excluded when filtering, and placed last when sorting.

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.

query RecommendedIngredients {
  recommendIngredients(search: {
    ingredients: "710,42"
    lang: "EN"
    page: "0,10"
  }) {
    ingredients {
      id
      name
      family {
        name
      }
    }
  }
}

{
  "data": {
    "recommendIngredients": {
      "ingredients": [
        {
          "id": "9",
          "name": "Aldehyde",
          "family": {
            "name": "ALDEHYDIC"
          }
        },
        {
          "id": "12",
          "name": "Allspice",
          "family": {
            "name": "SPICY"
          }
        }
      ]
    }
  }
}

Perfumer recommendations

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

query RecommendedPerfumist {
  recommendedPerfumist(
    perfumes: ["100", "200", "300"]
    lang: "EN"
  ) {
    id
    name
    bio
    house
    image1 {
      urls {
        low
        mid
      }
    }
  }
}

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

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

Getting Started

Guides

API Reference

Recommendations

Personalized recommendations

The business impact

What you can build

Match score

User-scoped recommendations

Scoping to a catalog

Custom recommendation rules

Filtering results

Price-based filtering and sorting

Ingredient recommendations

Perfumer recommendations

​Personalized recommendations

​The business impact

​What you can build

​Recommend similar perfumes

​Match score

​Recommend by EAN

​User-scoped recommendations

​Scoping to a catalog

​Custom recommendation rules

​Filtering results

​Price-based filtering and sorting

​Ingredient recommendations

​Perfumer recommendations

Personalized recommendations

The business impact

What you can build

Recommend similar perfumes

Match score

Recommend by EAN

User-scoped recommendations

Scoping to a catalog

Custom recommendation rules

Filtering results

Price-based filtering and sorting

Ingredient recommendations

Perfumer recommendations