Catalogue & recommendations
The merchant uses OpenApp as a personalised recommendation engine. No payment or checkout integration is required. The merchant shares their product catalogue and order history with OpenApp, and queries OpenApp for personalised product recommendations to display to users.
Required endpoints
| Endpoint | Direction | Purpose |
|---|---|---|
| Catalogue polling | OpenApp → Merchant | OpenApp syncs the product catalogue; product ids must be consistent across all APIs |
| Order feed | Merchant → OpenApp | Push order history (backfill at least 12 months) and ongoing orders so the engine can learn purchase patterns |
| User recommendations | Merchant → OpenApp | Query personalised product recommendations by user; returns three lists: top picks, replenishment, and discovery |
Optional endpoints
| Endpoint | Direction | Purpose |
|---|---|---|
| Wishlist feed | Merchant → OpenApp | Snapshot of a user's saved/wishlist products; improves recommendation quality for users who have not yet purchased |
Notes
Product IDs - the catalogue variant id is the key that ties all recommendation data together. The same variant id must appear in the order feed and wishlist feed, and OpenApp returns the same id in recommendation responses so the merchant can add recommended products to a basket without any mapping.
User identifiers - the loggedUser field in the order feed and wishlist feed is the merchant's own stable user identifier. OpenApp does not associate it with any OpenApp account.
Initial backfill - push at least the last 12 months of order history through the order feed before going live to give the recommendation engine enough signal. Backfilling and subsequent ongoing ingestion use the same endpoint. Re-sending an orderId replaces the stored order, so partial or rejected orders can be re-sent without side effects.
Processing delay - after the initial catalogue ingestion, OpenApp needs time to process the data before order ingestion and recommendations retrieval become available. Until processing completes, both endpoints respond 409 RecommendationsNotReadyException. Wait for confirmation from OpenApp before starting the order backfill.
Cancellations - re-send a previously sent order with status: CANCELLED to remove it from the engine. Products not yet known from the catalogue at ingestion time are reported back in ignoredProducts. Re-send the order after the next catalogue synchronization to capture them.