Skip to content

Interactions

Basic properties

They all have similar properties, let's have a look at them:

  • timestamp: Optional[str] - the time of an interaction timed in miliseconds, could be a number or a string (with a valid ms number). This will play an important role in identifying frequently bought together items so ideally you should provided it as much as possible.
  • recommendation_id: Optional[str] - the id that was returned to you along with the recommendation data. It is highly recommended that you save that id and send it along with the interaction if that's the case (will be used for providing you with metrics as well later on)
  • user_id: str - The user id that corresponds the id of the user in your database
  • item_id: str - The item id that corresponds the id of the item in your database
  • value: float - This property only exists in ratings payload. Should be any positive float number between 0 and 5.

Optional properties

These are all optional and are used only in some interactions as you can find in docs:

  • price: - the price of an item the user purchased it for
  • amount: - The amount of pieces if a user purchases more than one of the same product
  • duration: - The amount of time a user stared at a product (in ms)

Send interactions

Interactions are the most valuable information for the algorithms in the recommender engine.

The types of interactions are listed bellow:

  • bookmark: it will be sent to the system every time a user bookmarks an item

  • rating: it will be sent to the system every time a user rates an item

  • purchase: it will be sent every time a user completes the main desired goal (a conversion).

  • cart addition: - it will be sent to the system every time a user adds an item into their cart

  • view: it will be sent to the system every time a user views a detail of an item

The endpoints are consistent in the form of:

  • [POST] /v1/{interaction_type} to create an interaction
  • [GET] /v1/users/{user_id}/{interaction_type} to list all the interactions of this type of a specific user
  • [GET] /v1/items/{item_id}/{interaction_type} to list all the interactions of this type with a specific item

  • [DELETE] /v1/{interaction_type} to delete all the interactions. This endpoint is dynamic so you can determine the velocity of the delete. It accepts item_id, user_id, and timestamp. Eg: if you only pass an item_id this call will delete all the interactions containing this specific item. If you pass a user_id as well it will delete the interactions between this user and this item, and if you pass a timestamp the interactions that match all of the three criteria will be deleted.

  • [POST] /v1/purchases/batch This endpoint allows to create batch purchases, it is only available for the purchases for the moment. It works similarly as the normal create but it accepts an array as an input. You can find more info here.

Transfer user interactions

We provide an endpoint for transfering interactions from one user to another. One common use case might be if you have recorded the activity of a guest user and later on the same user registers into your e-shop. You can use the /v1/users/{from_user_id}/interactions/transfer/{to_user_id} or /v1/users/{user_id} including the new external_id to transfer all the interactions. The first endpoint provides a delete_user flag (defaults to True) to remove the "old" user, considering he is a guest.