Past, offline and omnichannel transactions import

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 auth_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 auth_user_id provided in the uploaded data must have the same value as the auth_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 receive 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 multiple 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, auth_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	Unique identifier of the purchased product. This must be the same identifier you use in your product catalog feed. Common formats include product SKU (e.g., SKU-123456), product ID (e.g., PROD-789012), or other unique product identifiers.
auth_user_id optional	Id of the user who purchased the product. (previously user_id, name still supported).
created_at optional	Timestamp of a purchase used to sort purchases in time. UTC timezone is expected

Caution

The identity value must exactly match the identifier used in your product catalog. Mismatched identifiers will prevent proper product matching and reduce the quality of recommendations and personalization.

The following table shows acceptable timestamp formats:

Format	Example
%Y-%m-%d %H:%M:%S.%f	2023-04-22 15:04:30.12312
%Y-%m-%d %H:%M:%S	2023-04-22 15:04:30
ISO 8601 format (Timezone designator must be omitted.)	2023-04-22T15:04:30

Danger

Including a timezone designator (e.g., Z or +02:00) in the timestamp string will result in an error.

Example of an import file in the json format:

{"order_id": "ORD-2023-001","identity": "SKU-WM-456","auth_user_id": "customer_42", "created_at": "2023-04-22 15:04:30.12312"}
{"order_id": "ORD-2023-001","identity": "SKU-KB-789","auth_user_id": "customer_42", "created_at": "2023-04-22 15:04:30.12312"}
{"order_id": "ORD-2023-002","identity": "PROD-123456","auth_user_id": "customer_15", "created_at": "2023-04-21 00:04:38.12121"}
{"order_id": "ORD-2023-002","identity": "PROD-789012","auth_user_id": "customer_15"}
{"order_id": "ORD-2023-003","identity": "SKU-HD-321"}

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 auth_user_id, created_at):

ORD-2023-001,SKU-WM-456,customer_42,"2023-04-22 15:04:30.12312"
ORD-2023-001,SKU-KB-789,customer_42,"2023-04-22 15:04:30.12312"
ORD-2023-002,PROD-123456,customer_15,"2023-04-21 00:04:38.12121"
ORD-2023-002,PROD-789012,customer_15
ORD-2023-003,SKU-HD-321

In case anonymized rows should be provided, the third column should remain empty:

ORD-2023-001,SKU-WM-456,,"2023-04-22 15:04:30.12312"
ORD-2023-001,SKU-KB-789,,"2023-04-22 15:04:30.12312"
ORD-2023-002,PROD-123456

Common questions

What format should I use for the identity field?

Use the same format that appears in your product catalog feed. If you’re unsure which identifier to use, check your existing product data or contact support@luigisbox.com

Can I mix different identity formats in the same file?

Yes, as long as each identifier matches the corresponding product in your catalog. For example, if some products in your catalog use SKU format and others use a different product ID system, you can use both in the transaction file. However, it’s recommended to use a consistent format across your entire catalog when possible.

API

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

Caution

This endpoint requires HMAC authentication. See API Principles 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. An 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.