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

# Taste Profile

> [!NOTE]
>
> Taste Profile is available for enterprise customers; contact
> [support@channel3.ai](mailto:support@channel3.ai) for access.

A **taste profile** is a saved ranking configuration that tunes which products rise to the top for your shoppers. You pass it as `config.taste_profile_id`, the same way you pass `config.collection_id`.

## Pass a taste profile

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const results = await client.products.search({
  query: "table lamp",
  config: {
    taste_profile_id: "TASTE_PROFILE_ID",
    collection_id: "COLLECTION_ID", // optional
  },
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
results = client.products.search(
    query="table lamp",
    config={
        "taste_profile_id": "TASTE_PROFILE_ID",
        "collection_id": "COLLECTION_ID",  # optional
    },
)
```

It works on [search](/docs/api-reference/v1/search.md), in both the default and [agentic](/docs/guides/agentic-search.md) modes, and on [conversations](/docs/conversations/collections.md).

The Channel3 team sets up each profile with you. The sections below show what a profile can hold.

## Brand and website boosts

Boost (positive `weight`) or bury (negative `weight`, down to -1) products from listed brands or websites.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "boosts": [
    { "brand_ids": ["brand_abc123"], "weight": 0.5 },
    { "website_ids": ["web_def456"], "weight": -0.8 }
  ]
}
```

Boosted brands also get an extra retrieval pass, so they can appear even when the query alone would miss them. Brand boosts don't apply to searches for a specific product or queries that name a brand, so the shopper's intent wins.

## Price tier preference

Prefer brands by where they sit on price: `low`, `medium`, `high` or `xhigh`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "boosts": [{ "price_tiers": ["high", "xhigh"], "weight": 0.4 }]
}
```

Channel3 places each brand from where its products fall in each category's price distribution, so `high` means roughly the top 40% of brands by price.

## Conditions

Attach a `condition` to any rule so it only applies to some queries, categories or dates.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "brand_ids": ["brand_abc123"],
  "weight": 0.6,
  "condition": {
    "query_terms": [{ "value": "candle", "full_match": false }],
    "category_ids": ["home-decor"],
    "active_ranges": [{ "start": "2026-11-20", "end": "2026-12-31" }]
  }
}
```

* `query_terms`: with `full_match: true` the whole query must equal the term; otherwise the query must contain all its words.
* `category_ids`: the rule applies when the query maps to one of these categories.
* `active_ranges`: the rule applies only between `start` and `end`, for example a holiday season.

## Pins

Put a specific product at a fixed position (1–20) when a condition matches.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "pins": [
    {
      "product_id": "prod_xyz789",
      "position": 1,
      "condition": { "query_terms": [{ "value": "throw blanket", "full_match": true }] }
    }
  ]
}
```

A profile can hold up to 10 pins, and each pin needs a condition with `query_terms` or `category_ids`.

## Diversity

Cap how many results from one brand or one merchant show on a page.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "diversity": { "max_per_brand": 3, "max_per_merchant": 5 }
}
```

## Query rewrites

Rewrite the shopper's query before Channel3 searches.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "query_rewrites": {
    "replacements": [{ "term": "lamp shade", "replacement": "lampshade" }],
    "ignore_terms": [{ "term": "cheap" }],
    "one_way_synonyms": [{ "term": "dinnerware", "synonyms": ["plates"] }],
    "two_way_synonyms": [{ "terms": ["sofa", "couch"] }],
    "do_not_associate": [{ "term": "vase", "terms": ["vinyl", "record"] }]
  }
}
```

* `replacements`: swap one term for another.
* `ignore_terms`: drop words that don't help, like "cheap".
* `one_way_synonyms`: "dinnerware" also searches "plates", but not the reverse.
* `two_way_synonyms`: "sofa" and "couch" search for each other.
* `do_not_associate`: when the query has the term, drop results whose titles contain the listed terms, so "vase" never returns vinyl records.

## Example profile

A home-decor retailer that favours its premium brands, promotes candles for the holidays and keeps results varied:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "boosts": [
    { "brand_ids": ["brand_abc123", "brand_ghi789"], "weight": 0.5 },
    { "website_ids": ["web_def456"], "weight": -0.6 },
    { "price_tiers": ["high"], "weight": 0.3 },
    {
      "brand_ids": ["brand_jkl012"],
      "weight": 0.8,
      "condition": {
        "query_terms": [{ "value": "candle", "full_match": false }],
        "active_ranges": [{ "start": "2026-11-20", "end": "2026-12-31" }]
      }
    }
  ],
  "pins": [
    {
      "product_id": "prod_xyz789",
      "position": 1,
      "condition": { "query_terms": [{ "value": "throw blanket", "full_match": true }] }
    }
  ],
  "diversity": { "max_per_brand": 3 },
  "query_rewrites": {
    "replacements": [{ "term": "lamp shade", "replacement": "lampshade" }],
    "two_way_synonyms": [{ "terms": ["sofa", "couch"] }],
    "do_not_associate": [{ "term": "vase", "terms": ["vinyl", "record"] }]
  }
}
```

### Before and after

An illustration of the top five results for `throw blanket`, without and with the profile above. Brand A is `brand_abc123`, Brand B is `brand_ghi789`, and Store D is the buried website `web_def456`.

| Position | Without a taste profile | With the example profile | Why it moved |
| - | - | - | - |
| 1 | Chunky knit throw (Store D) | Wool herringbone throw (`prod_xyz789`) | Pinned to position 1 |
| 2 | Fleece throw (Brand C) | Linen throw (Brand A) | Brand A boosted |
| 3 | Sherpa throw (Store D) | Cashmere throw (Brand B) | Brand B boosted |
| 4 | Linen throw (Brand A) | Fleece throw (Brand C) | Unchanged, moved down by the boosts |
| 5 | Cotton waffle throw (Store D) | Velvet throw (Brand A) | Brand A boosted |

Store D's throws drop below the top five because its website is buried. They still appear further down: burying moves results, it doesn't remove them.

## How it applies

> [!NOTE]
>
> A taste profile adjusts ranking and recall on top of normal relevance; it
> doesn't filter the catalog. To limit which products can appear, use a
> [collection](/docs/guides/collections.md). A request can pass both.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.