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

# Recommendations Overview

> AI-powered product recommendations with visual similarity and behavioral signals

## Overview

Refine provides three types of recommendations, each optimized for different use cases:

| Type                                                                    | Best For                           | Data Required                |
| ----------------------------------------------------------------------- | ---------------------------------- | ---------------------------- |
| [Similar Items](/sdk/recommendations/similar-items)                     | Product pages, "You may also like" | Anchor product ID            |
| [Visitor Recommendations](/sdk/recommendations/visitor-recommendations) | Homepage, anonymous users          | Browsing history (automatic) |
| [User Recommendations](/sdk/recommendations/user-recommendations)       | Logged-in users, personalization   | User identification          |

## Quick Start

```typescript theme={null}
import { Refine } from '@refine-ai/sdk';

const refine = new Refine({
  apiKey: process.env.REFINE_API_KEY,
  organizationId: 'org_abc123',
  catalogId: 'cat_xyz789'
});

// Similar items (product page)
const similar = await refine.recs.similarItems({
  anchorId: 'sku_dress_001',
  topK: 8
});

// Visitor recommendations (homepage, anonymous)
const forVisitor = await refine.recs.forVisitor({
  configId: 'homepage_recs',
  topK: 12
});

// User recommendations (logged-in users)
refine.identify('user_12345');
const forUser = await refine.recs.forUser({
  configId: 'personalized_picks',
  topK: 12
});
```

## Configuration IDs

Visitor and user recommendations require a `configId` that references a recommendation configuration created in the Refine dashboard. Configurations define:

* **Strategy** — Collaborative filtering, content-based, hybrid
* **Weighting** — Balance between visual similarity and behavioral signals
* **Filters** — Default filters applied to all recommendations
* **Business rules** — Category diversity, price range constraints

Create configurations at: **Dashboard → Recommendations → Configurations**

<Note>
  Similar items don't require a configId — they work directly with any product in your catalog.
</Note>

## Tracking Recommendations

Always track when recommendations are served to enable analytics and feedback loops:

```typescript theme={null}
const recs = await refine.recs.similarItems({
  anchorId: 'sku_001',
  topK: 8
});

const recsContext = refine.events.trackRecommendations(
  recs.serveId,
  recs.results,
  'product_page',   // surface
  'similar-items',  // source
  { anchorId: 'sku_001' }
);

// Track user interactions
recsContext.trackClick(productId, position);
recsContext.trackView(productId, position);
recsContext.trackAddToCart(productId);
```

## Response Structure

All recommendation methods return the same structure:

```typescript theme={null}
interface RecommendationResponse {
  results: RecommendationItem[];
  serveId: string;
  totalResults: number;
}

interface RecommendationItem {
  productId: string;
  title: string;
  price: number;
  imageUrl: string;
  metadata: Record<string, any>;
  score: number;
}
```

<ResponseField name="results" type="RecommendationItem[]">
  Array of recommended products, ordered by relevance/score.
</ResponseField>

<ResponseField name="serveId" type="string">
  Unique identifier for this recommendation serve. Used for event tracking.
</ResponseField>

<ResponseField name="totalResults" type="number">
  Total number of available recommendations before `topK` limit.
</ResponseField>

## Filtering Recommendations

Apply filters to narrow recommendations:

```typescript theme={null}
const recs = await refine.recs.similarItems({
  anchorId: 'sku_dress_001',
  topK: 8,
  filters: [
    { field: 'price', operator: 'lte', value: 150 },
    { field: 'stock', operator: 'gt', value: 0 },
    { field: 'metadata.category', operator: 'eq', value: 'dresses' }
  ]
});
```

See [Filters](/sdk/search/filters) for all available operators.

## Visual Weight

For similar items, control the balance between visual similarity and other signals:

```typescript theme={null}
const recs = await refine.recs.similarItems({
  anchorId: 'sku_001',
  topK: 8,
  visualWeight: 0.7  // High visual similarity emphasis
});
```

| visualWeight | Behavior                          |
| ------------ | --------------------------------- |
| `0.0`        | Pure metadata/behavioral matching |
| `0.5`        | Balanced (default for most)       |
| `1.0`        | Pure visual similarity            |

## Recommendation Strategies by Page

| Page                 | Recommended Type | Configuration                |
| -------------------- | ---------------- | ---------------------------- |
| Product Detail Page  | Similar Items    | `anchorId` = current product |
| Homepage (anonymous) | Visitor Recs     | Popular/trending config      |
| Homepage (logged-in) | User Recs        | Personalized config          |
| Cart Page            | Similar Items    | Multiple anchors from cart   |
| Category Page        | Visitor Recs     | Category-specific config     |
| Search (no results)  | Visitor Recs     | Fallback/popular config      |

## Error Handling

```typescript theme={null}
import { 
  RefineNotFoundError,
  RefineValidationError 
} from '@refine-ai/sdk';

try {
  const recs = await refine.recs.similarItems({
    anchorId: 'invalid_sku',
    topK: 8
  });
} catch (error) {
  if (error instanceof RefineNotFoundError) {
    // Anchor product doesn't exist
    console.log('Product not found, showing popular items instead');
    return await refine.recs.forVisitor({ configId: 'popular', topK: 8 });
  }
  if (error instanceof RefineValidationError) {
    console.error('Invalid parameters:', error.message);
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Similar Items" icon="clone" href="/sdk/recommendations/similar-items">
    Product-based recommendations
  </Card>

  <Card title="Visitor Recommendations" icon="user" href="/sdk/recommendations/visitor-recommendations">
    Anonymous visitor personalization
  </Card>

  <Card title="User Recommendations" icon="user-check" href="/sdk/recommendations/user-recommendations">
    Logged-in user personalization
  </Card>

  <Card title="Event Tracking" icon="chart-line" href="/sdk/events/overview">
    Track recommendation interactions
  </Card>
</CardGroup>