Skip to main content
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

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

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

ParameterRequiredDescription
current_urlYesThe full URL of the page where the widget is rendered. Used to determine product context.
session_idNo32-char session identifier. Required for Browsing history recommendation type.
user_idNoPersistent user UUID. Enables cross-session personalization.
hashidNoSearch engine hash ID. Required when the widget is not tied to a specific search engine.
languageNoLanguage code (e.g. en, es). Filters results to the specified language.
price_nameNoCurrency code (e.g. EUR, USD). Formats prices in the response.
cart_items[]NoArray of { dfid } objects representing items currently in the user’s cart.
category_context[]NoCategory path context for category-aware recommendations.

​
Recommendation Types

The widget type configured in the Admin Panel determines what signals drive the recommendations:
TypeRequired fieldsDescription
Similar productscurrent_urlProducts similar to those on the current page
Browsing historycurrent_url, session_idProducts based on this session’s browsing behavior
Frequently bought togethercurrent_url, cart_items[]Products often purchased with cart items
Personalizedcurrent_url, user_idProducts personalized to the user’s history
Trendingcurrent_urlCurrently popular products
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

StatusErrorDescription
400Bad requestInvalid or missing parameters. details field lists field-level errors.
403Forbidden originRequest origin not in allowed domains
403Forbidden ipClient IP is blocklisted
404Not foundWidget ID does not exist
429Too many requestsRate limit exceeded
{
  "error": "Bad request",
  "details": {
    "current_url": ["is required"],
    "session_id": ["length must be less than or equal to 32"]
  }
}