Past, offline and omnichannel transactions import

After integrating with Luigi's Box, it takes some time to collect enough behavioral data (products bought together within the same order, by the same user, etc.) to achieve full effectiveness of our services. In order to shorten or completely overcome this ramp-up period, it's possible for clients to provide past user transactions they have collected before the integration. For omnichannel clients, in this way, it is possible to import user transactions outside collected channels (typically from brick&mortar stores).

Individual services can benefit from it in the following way:

  • Behavioral recommendation - The behavioral algorithms are trained on co-purchases (products bought in the same order) and need a high amount of data to learn good quality recommendations. In basic scenario, anonymous transactions could be used (see mandatory and optional attributes below).
  • Personalization - Non-anonymous transactions (the attribute user_id is present) help us provide personalized responses. This can be used in search, recommender, autocomplete, product listings etc. It's important to stress that the user_id provided in the uploaded data must have the same value as the user_id provided in a search / recommender / etc. requests. Otherwise, no personalization improvements can be expected.
  • Popularity of products - We will store the summarized statistics of interactions with the products and calculate popularity of the products based on them. This improves ranking of the products in results.

After successful transactions upload into API, the client will recive response message 200, meaning that the data were successfully uploaded. They will be processed later on background. In case of any error, whole import is canceled. API doesn't allow data removal or update. If needed, contact support@luigisbox.com. Upload of mutlipe data files (e.g. on weekly basis or one time split of a large file) will cause their cumulative usage. Data uploaded into API are used for up to 52 weeks.

Import file format

User transactions are expected to be organized into orders. A single order groups customer's transactions which happen at the same time and captures the ordering of these transactions in time. Currently, only product purchases may be included in the import. Other interaction types, such as product clicks, must be omitted. If two products were purchased together but do not have a sequential dependency, they can be arranged in any sequence in the order.

Currently, two data formats are supported:

  • json lines - a file must contain one interaction per line. Expected file extension is .json
  • csv - a file must not contain csv header. The order of provided attributes is predefined. Expected file extension is .csv.

There are two mandatory attributes order_id and identity, which are used as the basis for global (anonymous) co-purchases learning (used in recommenders). The file can also contain two additional attributes, user_id and created_at, which, if present, allow the transaction metadata to be stored in a user profile and improve personalization (used in all Luigi's Box services).

Attribute Description
order_id required Any value that enables identification of products (rows) purchased in the same order.
identityrequired Resource identifier of the purchased product.
user_id optional Id of the user who purchased the product.
created_at optional Timestamp of a purchase used to sort purchases in time. UTC timezone is expected

Example of an import file in the json format:

{"order_id": "1","identity": "/p/123","user_id": "4", "created_at": "2023-04-22 15:04:30.12312"}
{"order_id": "1","identity": "/p/234","user_id": "4", "created_at": "2023-04-22 15:01:33.12345"}
{"order_id": "2","identity": "/p/123","user_id": "3", "created_at": "2023-04-21 00:04:38.12121"}
{"order_id": "2","identity": "/p/345","user_id": "3"}

Example of an import file in the csv format. File should not contain the header, rows contain fields in the following order - order_id, identity (optionally followed by user_id, created_at):

1,/p/123,4,"2023-04-22 15:04:30.12312"
1,/p/234,4,"2023-04-22 15:01:33.12345"
2,/p/123,3,"2023-04-21 00:04:38.12121"
2,/p/345,3

API

POST https://live.luigisbox.com/v1/interactions/<TRACKER_ID>/files

This endpoint requires HMAC authentication. Refer to the Authentication section for details.

Request Headers

Header Content
Content-Type multipart/form-data; boundary=sk13jk8sd823j9

Keep in mind that when the HMAC token is generated, the provided Content-Type should be multipart/form-data, without the boundary.

Request Body

The request body is a file containing historical transactions. File format details are described in the section Import file format.

Form Content
file @"/path/to/file.json"

For more information see OpenAPI Specification.

Restrictions

  1. The size of any uploaded file cannot be larger than 1 GB. Files exceeding this limit will be rejected. Reach out to support@luigisbox.com if you need to upload larger files.
  2. n uploaded file must fully transmit within 10 minutes. If the upload takes longer than the 10-minute timeout limit, an error will be returned and the upload canceled. If you encounter issues while uploading, reach out to support@luigisbox.com.