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
Schemat

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

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

topPicksobiektOpcjonalne

Limits for the topPicks list. All fields are optional; omit to use the defaults.

Pokaż parametry podrzędneUkryj parametry podrzędne2

itemsintegerOpcjonalne

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

minimum: 1 · maximum: 200

alternativesintegerOpcjonalne

Maximum number of alternative products to return per top-pick item. Defaults to 3.

minimum: 0 · maximum: 10

replenishmentobiektOpcjonalne

Limits for the replenishment list. All fields are optional; omit to use the defaults.

Pokaż parametry podrzędneUkryj parametry podrzędne2

itemsintegerOpcjonalne

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

minimum: 1 · maximum: 200

alternativesintegerOpcjonalne

Maximum number of alternative products to return per replenishment item. Defaults to 3.

minimum: 0 · maximum: 10

discoveryobiektOpcjonalne

Limits for the discovery list. All fields are optional; omit to use the defaults.

Pokaż parametry podrzędneUkryj parametry podrzędne2

itemsintegerOpcjonalne

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

minimum: 1 · maximum: 200

alternativesintegerOpcjonalne

Maximum number of alternative products to return per discovery item. Defaults to 3.

minimum: 0 · maximum: 10

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": "Limits for the topPicks list. All fields are optional; omit to use the defaults.",
          "additionalProperties": false,
          "type": "object",
          "properties": {
            "items": {
              "description": "Maximum number of top-pick items to return. Defaults to 20.",
              "minimum": 1,
              "maximum": 200,
              "type": "integer",
              "title": "items"
            },
            "alternatives": {
              "description": "Maximum number of alternative products to return per top-pick item. Defaults to 3.",
              "minimum": 0,
              "maximum": 10,
              "type": "integer",
              "title": "alternatives"
            }
          },
          "title": "topPicks"
        },
        "replenishment": {
          "description": "Limits for the replenishment list. All fields are optional; omit to use the defaults.",
          "additionalProperties": false,
          "type": "object",
          "properties": {
            "items": {
              "description": "Maximum number of replenishment items to return. Defaults to 20.",
              "minimum": 1,
              "maximum": 200,
              "type": "integer",
              "title": "items"
            },
            "alternatives": {
              "description": "Maximum number of alternative products to return per replenishment item. Defaults to 3.",
              "minimum": 0,
              "maximum": 10,
              "type": "integer",
              "title": "alternatives"
            }
          },
          "title": "replenishment"
        },
        "discovery": {
          "description": "Limits for the discovery list. All fields are optional; omit to use the defaults.",
          "additionalProperties": false,
          "type": "object",
          "properties": {
            "items": {
              "description": "Maximum number of discovery items to return. Defaults to 20.",
              "minimum": 1,
              "maximum": 200,
              "type": "integer",
              "title": "items"
            },
            "alternatives": {
              "description": "Maximum number of alternative products to return per discovery item. Defaults to 3.",
              "minimum": 0,
              "maximum": 10,
              "type": "integer",
              "title": "alternatives"
            }
          },
          "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ź
Schemat

{
  "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"
}

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ę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

alternativestablica typu AlternativeProductOpcjonalne

Substitute products to offer instead of this item if it cannot be shown, e.g. because it is out of stock by the time of display. Ordered by relevance; the merchant may show any number of them, including none. Bounded by limits.topPicks.alternatives.

Pokaż parametry podrzędneUkryj parametry podrzędne3

idstringWymagane

The catalogue variant ID of the alternative product.

maxLength: 36

eanstringOpcjonalne

The ean (or other barcode) of the alternative 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ędne5

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

alternativestablica typu AlternativeProductOpcjonalne

Pokaż parametry podrzędneUkryj parametry podrzędne3

idstringWymagane

The catalogue variant ID of the alternative product.

maxLength: 36

eanstringOpcjonalne

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

maxLength: 36

quantityintegerWymagane

The proposed number of items to add to the basket.

minimum: 1

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ędne5

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

alternativestablica typu AlternativeProductOpcjonalne

Pokaż parametry podrzędneUkryj parametry podrzędne3

idstringWymagane

The catalogue variant ID of the alternative product.

maxLength: 36

eanstringOpcjonalne

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

maxLength: 36

quantityintegerWymagane

The proposed number of items to add to the basket.

minimum: 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"
        },
        "alternatives": {
          "description": "Substitute products to offer instead of this item if it cannot be shown, e.g. because it is out of stock by the time of display. Ordered by relevance; the merchant may show any number of them, including none. Bounded by limits.topPicks.alternatives.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/AlternativeProduct"
          },
          "title": "alternatives"
        }
      },
      "required": [
        "id",
        "quantity"
      ]
    },
    "AlternativeProduct": {
      "title": "AlternativeProduct",
      "type": "object",
      "properties": {
        "id": {
          "description": "The catalogue variant ID of the alternative product.",
          "maxLength": 36,
          "type": "string",
          "title": "id"
        },
        "ean": {
          "description": "The ean (or other barcode) of the alternative 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"
        },
        "alternatives": {
          "description": "Substitute products to offer instead of this item if it cannot be shown, e.g. because it is out of stock by the time of display. Ordered by relevance; the merchant may show any number of them, including none. Bounded by limits.replenishment.alternatives.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/AlternativeProduct"
          },
          "title": "alternatives"
        }
      },
      "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"
        },
        "alternatives": {
          "description": "Substitute products to offer instead of this item if it cannot be shown, e.g. because it is out of stock by the time of display. Ordered by relevance; the merchant may show any number of them, including none. Bounded by limits.discovery.alternatives.",
          "type": "array",
          "items": {
            "$ref": "#/definitions/AlternativeProduct"
          },
          "title": "alternatives"
        }
      },
      "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

Żądanie​

Odpowiedź​

Błędy​

Żądanie

Odpowiedź

Błędy