Recommendations

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

Parameter	Required	Description
`brand`	Yes unless a server default is configured	Distribution channel name or domain, for example `Weebora` or `weebora.com`.
`locale`	Yes unless a server default is configured	Page/navigation locale, for example `it`, `en`, `es`, or `fr`.
`top_n`	No	Maximum number of products to return. Limits depend on the endpoint.
`slim`	No	When `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.

Overview

Integrations

Checkout flow (internal)

Overview

Required scope

Common parameters

Examples

Product detail recommendations

Search catalog with filters

Response shape

​Overview

​Required scope

​Common parameters

​Examples

​Product detail recommendations

​Search catalog with filters

​Response shape

Overview

Required scope

Common parameters

Examples

Product detail recommendations

Search catalog with filters

Response shape