Skip to main content

User recommendations

The user recommendations call returns three lists of products tailored to a specific user:

  • topPicks - products the user should buy right now.
  • replenishment - products the user regularly buys but does not need right now.
  • discovery - products the user might be interested in.

Every item, in any of the three lists, may carry alternatives - substitute products to show instead if the item itself cannot be displayed (e.g. out of stock by the time of rendering).

Request​

Recommendations are requested by a POST to the following endpoint:

POST {{OpenAppUrl}}/merchant/v1/recommendations/user
{
  "loggedUser": "user-id-from-webshop",
  "limits": {
    "topPicks": {
      "items": 3,
      "alternatives": 2
    },
    "replenishment": {
      "items": 5,
      "alternatives": 1
    },
    "discovery": {
      "items": 5,
      "alternatives": 1
    }
  }
}

Each list has a configurable items limit (default 20, max 200) and a configurable alternatives limit, capping the number of alternative products returned per item in that list (default 3, max 10). Omit limits or any of its fields to use the defaults.

Response​

{
  "topPicks": [
    {
      "id": "id124",
      "ean": "5901234123464",
      "quantity": 1,
      "alternatives": [
        {
          "id": "id123-red",
          "ean": "5901234123457",
          "quantity": 1
        }
      ]
    }
  ],
  "replenishment": [
    {
      "id": "id123-red",
      "ean": "5901234123457",
      "quantity": 2,
      "expectedAt": "2026-06-20T00:00:00.000Z",
      "alternatives": [
        {
          "id": "id124",
          "ean": "5901234123464",
          "quantity": 2
        }
      ]
    }
  ],
  "discovery": [
    {
      "id": "id123-blue",
      "ean": "5901234123471",
      "quantity": 1,
      "score": 0.44,
      "alternatives": [
        {
          "id": "id123-red",
          "ean": "5901234123457",
          "quantity": 1
        }
      ]
    }
  ],
  "expiresAt": "2026-06-10T09:42:00.000Z"
}

Only products known from the catalogue and currently available are returned. Any list can be shorter than its limit - or empty - when OpenApp has no sufficiently relevant recommendations. For a loggedUser OpenApp has not yet seen in the order feed, all three lists are empty. The merchant should design placements to handle empty lists gracefully.

Items within each list are returned in a stable sort order. Applying a presentation order that is pleasant for the user - for example grouping by product category - is the merchant's responsibility.

Recommendations for a user are recalculated once a day. A product the user has just purchased may still appear in the lists until the next recalculation. The merchant should hide recently purchased products when rendering the placement.

When expiresAt is present, the response can be cached and reused for the same user until that moment - it marks when the next recalculation will be available. When expiresAt is absent, the response must not be cached.

info

The call may take a few seconds and must not block the user. Fetch recommendations asynchronously - for example ahead of time or in a background request - and render the placement when the response arrives.

Errors​

Error nameCode
RecommendationValidationException400
RecommendationsNotReadyException409