Rekomendacje użytkownika

Wywołanie rekomendacji użytkownika zwraca trzy listy produktów dopasowanych do konkretnego użytkownika:

• topPicks - produkty, które użytkownik powinien kupić teraz.
• replenishment - produkty, które użytkownik regularnie kupuje, ale których teraz nie potrzebuje.
• discovery - produkty, którymi użytkownik może być zainteresowany.

Żądanie

Rekomendacje są pobierane żądaniem POST do następującego endpointu:

POST {{OpenAppUrl}}/merchant/v1/recommendations/user

Żądanie

{
  "loggedUser": "user-id-from-webshop",
  "limits": {
    "topPicks": 3,
    "replenishment": 5,
    "discovery": 5
  }
}

Schemat

loggedUserstringWymagane

The merchant's own stable identifier for the user.

maxLength: 255

limitsobiektOpcjonalne

Maximum number of items to return per list. All fields are optional; omit to use the defaults.

Pokaż parametry podrzędneUkryj parametry podrzędne3

topPicksintegerOpcjonalne

Maximum number of top-pick items to return. Defaults to 20.

minimum: 1 · maximum: 200

replenishmentintegerOpcjonalne

Maximum number of replenishment items to return. Defaults to 20.

minimum: 1 · maximum: 200

discoveryintegerOpcjonalne

Maximum number of discovery items to return. Defaults to 20.

minimum: 1 · maximum: 200

Surowy schemat JSON

{
  "description": "Request for product recommendations for a user",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "loggedUser": {
      "description": "The merchant's own stable identifier for the user.",
      "maxLength": 255,
      "type": "string",
      "title": "loggedUser"
    },
    "limits": {
      "description": "Maximum number of items to return per list. All fields are optional; omit to use the defaults.",
      "additionalProperties": false,
      "type": "object",
      "properties": {
        "topPicks": {
          "description": "Maximum number of top-pick items to return. Defaults to 20.",
          "minimum": 1,
          "maximum": 200,
          "type": "integer",
          "title": "topPicks"
        },
        "replenishment": {
          "description": "Maximum number of replenishment items to return. Defaults to 20.",
          "minimum": 1,
          "maximum": 200,
          "type": "integer",
          "title": "replenishment"
        },
        "discovery": {
          "description": "Maximum number of discovery items to return. Defaults to 20.",
          "minimum": 1,
          "maximum": 200,
          "type": "integer",
          "title": "discovery"
        }
      },
      "title": "limits"
    }
  },
  "required": [
    "loggedUser"
  ],
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Każda lista ma konfigurowalny limit (domyślnie 20, maksymalnie 200). Pomiń limits lub dowolne jego pole, aby użyć wartości domyślnych.

Odpowiedź

Odpowiedź

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

Schemat

topPickstablica typu RecommendedProductWymagane

Products the user should buy right now, ordered in a stable sort order. Applying a presentation order pleasant for the user (e.g. grouping by product category) is the merchant's responsibility.

Pokaż parametry podrzędneUkryj parametry podrzędne3

idstringWymagane

The catalogue variant ID of the recommended product.

maxLength: 36

eanstringOpcjonalne

The ean (or other barcode) of the recommended product, as known from the catalogue.

maxLength: 36

quantityintegerWymagane

The proposed number of items to add to the basket.

minimum: 1

replenishmenttablica typu ReplenishmentProductWymagane

Products the user regularly buys but does not need right now - returned in a stable sort order. Each item includes an expectedAt date indicating when the user is expected to want to buy it. A product that appears in topPicks will not appear here. Applying a presentation order pleasant for the user (e.g. grouping by product category) is the merchant's responsibility.

Pokaż parametry podrzędneUkryj parametry podrzędne4

idstringWymagane

The catalogue variant ID of the recommended product.

maxLength: 36

eanstringOpcjonalne

The ean (or other barcode) of the recommended product, as known from the catalogue.

maxLength: 36

quantityintegerWymagane

The proposed number of items to add to the basket.

minimum: 1

expectedAtstringWymagane

The moment when the user is expected to want to buy this product.

format: date-time

discoverytablica typu DiscoveryProductWymagane

Products the user might be interested in, returned in a stable sort order. Each item carries a relevance score. Applying a presentation order pleasant for the user (e.g. grouping by product category) is the merchant's responsibility.

Pokaż parametry podrzędneUkryj parametry podrzędne4

idstringWymagane

The catalogue variant ID of the recommended product.

maxLength: 36

eanstringOpcjonalne

The ean (or other barcode) of the recommended product, as known from the catalogue.

maxLength: 36

quantityintegerWymagane

The proposed number of items to add to the basket.

minimum: 1

scorenumberWymagane

The relevance of the recommendation, between 0 and 1. Higher is more relevant.

minimum: 0 · maximum: 1

expiresAtstringOpcjonalne

The moment until which the recommendations can be cached and reused for the same user. When absent, the response must not be cached.

format: date-time

Surowy schemat JSON

{
  "description": "Product recommendations returned for a user",
  "additionalProperties": false,
  "type": "object",
  "properties": {
    "topPicks": {
      "description": "Products the user should buy right now, ordered in a stable sort order. Applying a presentation order pleasant for the user (e.g. grouping by product category) is the merchant's responsibility.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/RecommendedProduct"
      },
      "title": "topPicks"
    },
    "replenishment": {
      "description": "Products the user regularly buys but does not need right now - returned in a stable sort order. Each item includes an expectedAt date indicating when the user is expected to want to buy it. A product that appears in topPicks will not appear here. Applying a presentation order pleasant for the user (e.g. grouping by product category) is the merchant's responsibility.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/ReplenishmentProduct"
      },
      "title": "replenishment"
    },
    "discovery": {
      "description": "Products the user might be interested in, returned in a stable sort order. Each item carries a relevance score. Applying a presentation order pleasant for the user (e.g. grouping by product category) is the merchant's responsibility.",
      "type": "array",
      "items": {
        "$ref": "#/definitions/DiscoveryProduct"
      },
      "title": "discovery"
    },
    "expiresAt": {
      "description": "The moment until which the recommendations can be cached and reused for the same user. When absent, the response must not be cached.",
      "format": "date-time",
      "type": "string",
      "title": "expiresAt"
    }
  },
  "required": [
    "topPicks",
    "replenishment",
    "discovery"
  ],
  "definitions": {
    "RecommendedProduct": {
      "title": "RecommendedProduct",
      "type": "object",
      "properties": {
        "id": {
          "description": "The catalogue variant ID of the recommended product.",
          "maxLength": 36,
          "type": "string",
          "title": "id"
        },
        "ean": {
          "description": "The ean (or other barcode) of the recommended product, as known from the catalogue.",
          "maxLength": 36,
          "type": "string",
          "title": "ean"
        },
        "quantity": {
          "description": "The proposed number of items to add to the basket.",
          "minimum": 1,
          "type": "integer",
          "title": "quantity"
        }
      },
      "required": [
        "id",
        "quantity"
      ]
    },
    "ReplenishmentProduct": {
      "title": "ReplenishmentProduct",
      "type": "object",
      "properties": {
        "id": {
          "description": "The catalogue variant ID of the recommended product.",
          "maxLength": 36,
          "type": "string",
          "title": "id"
        },
        "ean": {
          "description": "The ean (or other barcode) of the recommended product, as known from the catalogue.",
          "maxLength": 36,
          "type": "string",
          "title": "ean"
        },
        "quantity": {
          "description": "The proposed number of items to add to the basket.",
          "minimum": 1,
          "type": "integer",
          "title": "quantity"
        },
        "expectedAt": {
          "description": "The moment when the user is expected to want to buy this product.",
          "format": "date-time",
          "type": "string",
          "title": "expectedAt"
        }
      },
      "required": [
        "id",
        "quantity",
        "expectedAt"
      ]
    },
    "DiscoveryProduct": {
      "title": "DiscoveryProduct",
      "type": "object",
      "properties": {
        "id": {
          "description": "The catalogue variant ID of the recommended product.",
          "maxLength": 36,
          "type": "string",
          "title": "id"
        },
        "ean": {
          "description": "The ean (or other barcode) of the recommended product, as known from the catalogue.",
          "maxLength": 36,
          "type": "string",
          "title": "ean"
        },
        "quantity": {
          "description": "The proposed number of items to add to the basket.",
          "minimum": 1,
          "type": "integer",
          "title": "quantity"
        },
        "score": {
          "description": "The relevance of the recommendation, between 0 and 1. Higher is more relevant.",
          "minimum": 0,
          "maximum": 1,
          "type": "number",
          "title": "score"
        }
      },
      "required": [
        "id",
        "quantity",
        "score"
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Zwracane są wyłącznie produkty znane z katalogu i aktualnie dostępne. Każda lista może być krótsza niż jej limit - lub pusta - gdy OpenApp nie ma wystarczająco trafnych rekomendacji. Dla loggedUser, którego OpenApp nie widział jeszcze w feedzie zamówień, wszystkie trzy listy są puste. Merchant powinien zaprojektować listy produktów tak, aby obsługiwały puste wyniki.

Elementy na każdej liście są zwracane w stabilnej kolejności sortowania. Zastosowanie kolejności prezentacji przyjaznej dla użytkownika - na przykład grupowanie według kategorii produktów - zostaje po stronie merchanta.

Rekomendacje dla użytkownika są przeliczane raz dziennie. Produkt, który użytkownik właśnie kupił, może nadal pojawiać się na listach do następnego przeliczenia. Merchant powinien ukrywać niedawno zakupione produkty podczas renderowania listy.

Gdy pole expiresAt jest obecne, odpowiedź może być cachowana i używana ponownie dla tego samego użytkownika do tego momentu - wskazuje on, kiedy będzie dostępne następne przeliczenie. Gdy expiresAt jest nieobecne, odpowiedzi nie należy cachować.

informacja

Wywołanie może trwać kilka sekund i nie może blokować użytkownika. Pobieraj rekomendacje asynchronicznie - na przykład z wyprzedzeniem lub w tle - i renderuj listę produktów po otrzymaniu odpowiedzi.

Błędy

Nazwa błędu	Kod
RecommendationValidationException	400
RecommendationsNotReadyException	409