​
Overview

Use /v1/recommendations/* to retrieve ranked product lists for product detail pages, category pages, destination pages, and search/browse pages. These routes use the same HoJ authentication as the rest of the Distribution API. Clients send Authorization: Bearer <api key|oauth token> to api.hofj.com; the BFF calls the recommender service server-side with its own upstream secret.

​
Required scope

Your client must include recommendations in allowedEntities. The requested brand must resolve to a distribution channel id included in your allowedChannelIds.

​
Common parameters

ParameterRequiredDescription
brandYes unless a server default is configuredDistribution channel name or domain, for example Weebora or weebora.com.
localeYes unless a server default is configuredPage/navigation locale, for example it, en, es, or fr.
top_nNoMaximum number of products to return. Limits depend on the endpoint.
slimNoWhen true, returns lightweight recommendation items.

​
Examples

​
Product detail recommendations

BASE="https://staging.api.hofj.com"
TOKEN="replace-with-hoj-api-key-or-oauth-token"

curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "${BASE}/v1/recommendations/product?brand=Weebora&locale=it&product_id=1127&top_n=5"

​
Search catalog with filters

curl -sS -H "Authorization: Bearer ${TOKEN}" \
  "${BASE}/v1/recommendations/search?brand=Weebora&locale=it&keyword=padel&price_max=500&top_n=10"

​
Response shape

Responses follow the BFF envelope: 
{
  "data": {
    "locale": "it",
    "products": []
  },
  "meta": {
    "brand": "weebora.com",
    "channelId": 1,
    "cacheLoadedAt": "2026-04-24T03:00:00+00:00"
  }
}
The API normalizes recommender payload keys to camelCase and exposes recommender cache timing in meta.cacheLoadedAt when available.