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

# Perfumes

## Perfume data

Perfumes are the central entity in WikiParfum. Each perfume record includes rich metadata — brand, olfactive family, ingredients, perfumers, imagery, and more — enabling product pages, comparison tools, and enriched catalog experiences.

## Retrieve a single perfume

Fetch a perfume by its unique ID, URL-friendly slug, or EAN barcode.

### By ID

<CodeGroup>
  ```graphql Query theme={null}
  query PerfumeById {
    findPerfumeById(id: "424", lang: "EN") {
      id
      name
      description
      brand {
        name
      }
      family {
        name
        color
      }
      secondaryFamily {
        name
      }
      gender
      year
      ingredients {
        id
        name
        proportion
        hero
      }
      image {
        urls {
          low
          mid
          high
        }
      }
      slug
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "findPerfumeById": {
        "id": "424",
        "name": "GOOD GIRL",
        "description": "Good Girl is a fragrance as powerful as it is sensual. An audacious blend of dark and light elements. For the woman who knows when it's good to be bad.",
        "brand": {
          "name": "Carolina Herrera"
        },
        "family": {
          "name": "AMBERY (ORIENTAL)",
          "color": "#B41F24"
        },
        "secondaryFamily": {
          "name": "AMBERY (ORIENTAL)"
        },
        "gender": "F",
        "year": 2016,
        "ingredients": [
          {
            "id": "13",
            "name": "Almond",
            "proportion": null,
            "hero": 0
          },
          {
            "id": "115",
            "name": "Cocoa",
            "proportion": null,
            "hero": 0
          }
        ],
        "image": {
          "urls": {
            "low": "https://api-assets.wikiparfum.com/_resized/1trb5qms3qhq6u8ja6jc2pwj13zqn6q1u3lftxcoq2qq5th2obdx8be8kopg-w100-q85.jpg",
            "mid": "https://api-assets.wikiparfum.com/_resized/1trb5qms3qhq6u8ja6jc2pwj13zqn6q1u3lftxcoq2qq5th2obdx8be8kopg-w250-q85.jpg",
            "high": "https://api-assets.wikiparfum.com/_resized/1trb5qms3qhq6u8ja6jc2pwj13zqn6q1u3lftxcoq2qq5th2obdx8be8kopg-w500-q85.jpg"
          }
        },
        "slug": "good-girl"
      }
    }
  }
  ```
</CodeGroup>

### By slug

Useful for SEO-friendly URLs and deep linking.

<CodeGroup>
  ```graphql Query theme={null}
  query PerfumeBySlug {
    findPerfumeBySlug(slug: "good-girl", lang: "EN") {
      id
      name
      brand {
        name
      }
      family {
        name
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "findPerfumeBySlug": {
        "id": "424",
        "name": "GOOD GIRL",
        "brand": {
          "name": "Carolina Herrera"
        },
        "family": {
          "name": "AMBERY (ORIENTAL)"
        }
      }
    }
  }
  ```
</CodeGroup>

### By EAN

Look up a perfume using its barcode — ideal for scan-to-discover experiences.

<CodeGroup>
  ```graphql Query theme={null}
  query PerfumeByEAN {
    findPerfumeByEAN(ean: "8411061994351", lang: "EN") {
      id
      name
      brand {
        name
      }
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "findPerfumeByEAN": {
        "id": "424",
        "name": "GOOD GIRL",
        "brand": {
          "name": "Carolina Herrera"
        }
      }
    }
  }
  ```
</CodeGroup>

You can also look up multiple EANs at once:

<CodeGroup>
  ```graphql Query theme={null}
  query PerfumesByEANS {
    findPerfumesByEANS(
      eans: ["8411061994351", "0085715166067"]
      lang: "EN"
    ) {
      id
      name
      ean
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "findPerfumesByEANS": [
        {
          "id": "424",
          "name": "GOOD GIRL",
          "ean": "8411061994351"
        }
      ]
    }
  }
  ```
</CodeGroup>

## List and filter perfumes

Retrieve perfumes with full-text search, filters, sorting, and pagination.

<CodeGroup>
  ```graphql Query theme={null}
  query FilteredPerfumes {
    findPerfumes(search: {
      lang: "EN"
      search: "sauvage"
      page: "0,20"
      order_by: "name asc"
      filters: {
        gender: "M"
      }
    }) {
      id
      name
      brand {
        name
      }
      family {
        name
      }
      gender
      year
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "findPerfumes": [
        {
          "id": "1265",
          "name": "EAU SAUVAGE EAU DE TOILETTE",
          "brand": {
            "name": "Dior"
          },
          "family": {
            "name": "CITRUS"
          },
          "gender": "M",
          "year": 1966
        },
        {
          "id": "1900",
          "name": "SAUVAGE",
          "brand": {
            "name": "Dior"
          },
          "family": {
            "name": "AROMATIC FOUGERE"
          },
          "gender": "M",
          "year": 2015
        }
      ]
    }
  }
  ```
</CodeGroup>

### Filter by brand

<CodeGroup>
  ```graphql Query theme={null}
  query PerfumesByBrand {
    findPerfumes(search: {
      lang: "EN"
      brand: "42"
      page: "0,20"
    }) {
      id
      name
      year
    }
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "findPerfumes": [
        {
          "id": "108",
          "name": "BOSS BOTTLED INFINITE",
          "year": 2019
        },
        {
          "id": "109",
          "name": "BOSS BOTTLED",
          "year": 1998
        }
      ]
    }
  }
  ```
</CodeGroup>

### Filter by perfumist

```graphql theme={null}
query PerfumesByPerfumist {
  findPerfumes(search: {
    lang: "EN"
    perfumistSlug: "francis-kurkdjian"
    page: "0,20"
  }) {
    id
    name
    brand {
      name
    }
  }
}
```

## Recommended perfumes

Get perfumes similar to one or more input perfumes, ranked by olfactive proximity. See the [Recommendations guide](/wikiparfum-api/guides/recommendations) for business context and advanced patterns.

### By perfume ID

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

  ```json Response theme={null}
  {
    "data": {
      "recommendedPerfumes": [
        {
          "id": "734",
          "name": "HYPNOTIC POISON",
          "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",
          "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>

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

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. See [Sessions](/wikiparfum-api/getting-started/sessions) and [CRM Personalization](/wikiparfum-api/guides/crm-personalization) for details.

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

### Custom recommendation rules

Use `customRecommendation` to control which brands or perfumes appear in results. 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"
          }
        }
      ]
    }
  }
  ```
</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        |

### Filtered recommendations

Recommendations can be narrowed using standard filters. 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>

## Browse all WikiParfum perfumes

The `findPerfumesPublic` query returns perfumes from the entire WikiParfum database — not limited to your catalog. It uses a reduced `PerfumePublic` type with fewer fields, making it ideal for browsing, discovery, and public-facing experiences where you want to show the full fragrance universe.

<Note>
  **`findPerfumes` vs `findPerfumesPublic`:** `findPerfumes` returns perfumes from your catalog (scoped to your [Product Feed](/catalog-integration/product-feed)) with the full `Perfume` type. `findPerfumesPublic` returns all perfumes in WikiParfum's database with a reduced field set.
</Note>

<CodeGroup>
  ```graphql Query theme={null}
  query BrowseAllPerfumes {
    findPerfumesPublic(search: {
      lang: "EN"
      page: "0,10"
      order_by: "name asc"
      filters: {
        gender: "F"
        family: "floral"
      }
    }) {
      id
      name
      description
      gender
      brand {
        name
      }
      family {
        name
        color
      }
      secondaryFamily {
        name
      }
      image {
        urls {
          low
          mid
          high
        }
      }
      eans
    }
  }
  ```
</CodeGroup>

### PerfumePublic fields

The `PerfumePublic` type exposes a subset of the full `Perfume` type:

| Field             | Type                          | Description                                             |
| ----------------- | ----------------------------- | ------------------------------------------------------- |
| `id`              | `ID`                          | Unique perfume identifier                               |
| `name`            | `String`                      | Perfume name                                            |
| `description`     | `String`                      | Perfume description                                     |
| `gender`          | `String`                      | Target gender: `"F"`, `"M"`, or `"U"`                   |
| `brand`           | `{ name }`                    | Brand name                                              |
| `family`          | `{ name, color }`             | Primary olfactive family                                |
| `secondaryFamily` | `{ name, color }`             | Secondary olfactive family                              |
| `image`           | `{ urls { low, mid, high } }` | Resized image URLs                                      |
| `eans`            | `[String]`                    | EAN barcodes from the client's catalog for this perfume |

### Input parameters

`findPerfumesPublic` accepts a `PerfumesPublicSearch` input with the following fields:

| Parameter  | Type      | Description                                            |
| ---------- | --------- | ------------------------------------------------------ |
| `lang`     | `String`  | Language for localized content (e.g., `"EN"`, `"FR"`)  |
| `page`     | `String`  | Pagination: `"offset,limit"` (e.g., `"0,20"`)          |
| `order_by` | `String`  | Sort order (e.g., `"name asc"`)                        |
| `search`   | `String`  | Full-text search against name and brand                |
| `brand`    | `ID`      | Filter by brand ID                                     |
| `ids`      | `String`  | Filter by perfume IDs (comma-separated)                |
| `slugs`    | `String`  | Filter by perfume slugs (comma-separated)              |
| `filters`  | `Filters` | Standard [filters](/wikiparfum-api/features/filtering) |

## Key perfume fields

| Field                        | Description                                             |
| ---------------------------- | ------------------------------------------------------- |
| `name`                       | Perfume name                                            |
| `brand`                      | Brand information                                       |
| `family` / `secondaryFamily` | Olfactive family classification (primary and secondary) |
| `gender`                     | Target gender: `"F"`, `"M"`, or `"U"` (unisex)          |
| `year` / `month`             | Release date                                            |
| `ingredients`                | List of ingredients with `proportion` and `hero` flag   |
| `classification`             | Market segment: `"prestige"` or `"mass"`                |
| `slug`                       | URL-friendly identifier                                 |
| `ean` / `eans`               | Barcode(s)                                              |
| `image`                      | Resized image URLs (`low`, `mid`, `high`)               |
| `perfumers`                  | Perfumers who created the fragrance                     |
| `intensity`                  | Olfactive intensity score                               |
| `discontinued`               | Whether the perfume is discontinued                     |

<Note>
  When your account has a [Product Feed](/catalog-integration/product-feed) configured, the `eans` field returns only EANs that exist in your catalog — not all EANs known to WikiParfum for that perfume. This applies to both `Perfume` and `PerfumePublic` types. If no Product Feed is configured, all known EANs are returned.
</Note>