Skip to main content

Overview

The Recommendations API allows a merchant to use the OpenApp recommendation engine in his own shop. The merchant feeds OpenApp with purchase data and (optionally) wishlist data, and in return can query personalized product recommendations for a user - in the form of proposed catalogue variant ids, eans, and quantities.

The API consists of three parts:

  1. Order feed - the merchant pushes historical and ongoing order data (the purchased basket: products, quantities, prices) together with a user identifier. Orders placed through the OpenApp checkout are ingested automatically. The feed is for orders from the merchant's other sales channels.
  2. Wishlist feed (optional) - the merchant pushes the content of user wishlists as an additional signal for personalization.
  3. User recommendations - the merchant queries recommendations for a user by their identifier and receives three lists of proposed products: top picks, replenishment, and discovery.

The recommendation engine builds on the product catalogue, so an integrated Catalogue API is a prerequisite: recommendations only contain products that OpenApp knows from the catalogue, and out-of-stock or delisted products are excluded on a best-effort basis. After the initial catalogue ingestion, OpenApp needs time to process the data; order ingestion and recommendations retrieval become available only after that processing completes - until then, both endpoints respond 409 RecommendationsNotReadyException.

User identifiers​

All three parts of the API identify the user by the loggedUser field - the merchant's own stable identifier for the user. OpenApp does not attempt to associate it with any OpenApp account. The identifier must be:

  • stable: the same user must always be reported with the same value, across the order feed, the wishlist feed and recommendation queries;
  • unique per user within the merchant.

The identifier may be anonymized - OpenApp only needs it to correlate events across the feeds. Personal data such as names or email addresses must not be used as the identifier.

Every order must identify the user who placed it.