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

# Recommendations API

> Deliver personalized product recommendations using Doofinder's recommendation engine.

The Recommendations API powers recommendation widgets on your ecommerce site — showing users products they are likely to be interested in based on browsing history, cart contents, current page context, and user identity.

**Version:** v1

## Base URL

```
https://{search_zone}-recommendations.doofinder.com
```

Supported zones: `eu1`, `us1`, `ap1`

## Authentication

The Recommendations API does **not** use an `Authorization` header. Instead, the **widget ID** (a UUID configured in the Admin Panel) acts as the access credential and is passed in the URL path.

***

## How It Works

**1. Create a carousel in Admin Panel**

Go to **Recommendations** and click **Add Carousel**. Each carousel has a `widget_id` (UUID) that you use in the API.

**2. Call the API on page load**

POST to `/api/widget/{widget_id}` with context about the current page and user.

**3. Render the results**

The response contains a `results` array of product recommendations and currency formatting details.

***

## Endpoint

```
POST https://{zone}-recommendations.doofinder.com/api/widget/{widget_id}
```

### Request body

```json theme={null}
{
  "current_url": "https://shop.example.com/products/wireless-headphones",
  "session_id": "b2b89619844f4eb0b5fa19f28a19d679",
  "user_id": "8c80694b-354c-4533-acd1-e4b8e7d74b7b",
  "hashid": "de8f052ea612f95b6950d4013dd6ef38",
  "language": "en",
  "price_name": "EUR",
  "cart_items": [
    { "dfid": "de8f052ea612f95b6950d4013dd6ef38@product@e7b7a6c35b2d4afc94991bfc8100227a" }
  ],
  "category_context": []
}
```

### Response

```json theme={null}
{
  "title": "You might also like",
  "currency": {
    "code": "EUR",
    "label": "Euro",
    "format": "%v %s",
    "symbol": "€",
    "precision": 2,
    "decimal": ",",
    "thousand": "."
  },
  "fallback_action": "disabled",
  "results": [
    {
      "id": "SKU-099",
      "title": "Wireless Earbuds Pro",
      "price": 79.99,
      "url": "https://shop.example.com/products/wireless-earbuds-pro"
    }
  ]
}
```

***

## Request Parameters

| Parameter | Required | Description |
| - | - | - |
| `current_url` | **Yes** | The full URL of the page where the widget is rendered. Used to determine product context. |
| `session_id` | No | 32-char session identifier. Required for **Browsing history** recommendation type. |
| `user_id` | No | Persistent user UUID. Enables cross-session personalization. |
| `hashid` | No | Search engine hash ID. Required when the widget is not tied to a specific search engine. |
| `language` | No | Language code (e.g. `en`, `es`). Filters results to the specified language. |
| `price_name` | No | Currency code (e.g. `EUR`, `USD`). Formats prices in the response. |
| `cart_items[]` | No | Array of `{ dfid }` objects representing items currently in the user's cart. |
| `category_context[]` | No | Category path context for category-aware recommendations. |

***

## Recommendation Types

The widget type configured in the Admin Panel determines what signals drive the recommendations:

| Type | Required fields | Description |
| - | - | - |
| **Similar products** | `current_url` | Products similar to those on the current page |
| **Browsing history** | `current_url`, `session_id` | Products based on this session's browsing behavior |
| **Frequently bought together** | `current_url`, `cart_items[]` | Products often purchased with cart items |
| **Personalized** | `current_url`, `user_id` | Products personalized to the user's history |
| **Trending** | `current_url` | Currently popular products |

> [!NOTE]
>
> If the required signals are not provided for a recommendation type, the API falls back to a default strategy (if fallback is enabled for the widget). If no fallback is configured, an empty `results` array is returned.

***

## CORS

If your ecommerce site uses CORS, ensure the domain making the request is in your store's **Allowed Domains** list in the Admin Panel. Requests from unlisted domains return `403 Forbidden Origin`.

***

## Error Responses

| Status | Error | Description |
| - | - | - |
| `400` | `Bad request` | Invalid or missing parameters. `details` field lists field-level errors. |
| `403` | `Forbidden origin` | Request origin not in allowed domains |
| `403` | `Forbidden ip` | Client IP is blocklisted |
| `404` | `Not found` | Widget ID does not exist |
| `429` | `Too many requests` | Rate limit exceeded |

```json theme={null}
{
  "error": "Bad request",
  "details": {
    "current_url": ["is required"],
    "session_id": ["length must be less than or equal to 32"]
  }
}
```


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