Data priming order history

Data priming involves importing a retailer’s historical order data into Voyado Elevate to enable faster optimization of content and improved user outcomes based on historical sales patterns. The order history must be supplied as a UTF-8 encoded JSONL file that adheres to the specified data priming schema. If a product in the priming file is not yet in the cluster, its historical purchases are still stored. When the product is later added, it is treated as new (unless the release date is overridden). Although optional, data priming is highly recommended. If implemented, it must be executed as the final step of the integration process, prior to the system’s go-live. This process is performed only once and should include approximately three months of historical order data, regardless of the total order volume.

Market identifiers and product key conventions must be consistent across the catalog import, the order notifications, and the order history. The format of the customer keys in the order history must match the format of the keys used with HTTP requests. Ensure this is consistent.

Data priming syntax

Example

The following example adds two orders with a total of three products as priming data.

{"dateTime":"2017-10-14T12:00:00+01:00","customerKey":"d9528030-509c-4e0f-b585-7168f1e9feca","market":"UK","lines":[{"productKey":"P_555452-0446_UK","variantKey":"V_555452-0446_1_UK","quantity":3,"cost":2.2,"sellingPrice":5.5}]}
{"dateTime":"2017-10-14T12:00:05+01:00","customerKey":"e030d954-b585-280f-509c-68f171fee9ca","market":"UK","lines":[{"productKey":"P_335975-0444_UK","variantKey":"V_335975-0444_3_UK","quantity":1,"cost":3.5,"sellingPrice":4.2},{"productKey":"P_133449-0338_UK","quantity":2,"cost":5.1,"sellingPrice":8.5}]}

{
  "dateTime": "2017-10-14T12:00:05+01:00",
  "customerKey": "e030d954-b585-280f-509c-68f171fee9ca",
  "market": "UK",
  "lines": [
    {
      "productKey": "P_335975-0444_UK",
      "variantKey": "V_335975-0444_3_UK",
      "quantity": 1,
      "cost": 3.5,
      "sellingPrice": 4.2
    }
  ]
}

File specification

The file must be a UTF-8 encoded JSONL file, where each line is a single valid JSON object. Each JSON object represents an order that contains one or more purchased products and their associated purchase data. The order objects should be arranged in ascending chronological order, with the oldest entries appearing first and the newest entries last. The following elements are allowed in a priming JSONL file.

Name	Type	Description	Example
`dateTime`*	string	The time of the order. The time should be written in ISO 8601 format, including offset.	`2017-10-14T12:00:00+01:00`
`market`*	string	The Elevate market where the purchase was performed. Must match the market used in the data model.	`UK`
`lines`*	array	The element containing the `line` elements.	N/A
`line`*	object	The element containing all elements related to the purchase of a specific product in an order.	N/A
`productKey`*	string	The unique key of the purchased product. Must be the same as keys used for products in the catalog import.	`shirt_79709`
`variantKey`*	string	The unique variant key of the variant. Must be the same as keys used for variants in the catalog import.	`shirt_79709_M`
`customerKey`	string	The visitor ID. A SHA256 hash if the visitor was signed in, otherwise a UUID or GUID.	`5G7HJ...R77T1`
`quantity`	int	The quantity of the purchased product. The following bounds apply: `quantity` ≥ 1. Defaults to 1 if omitted.	`2`
`cost`	double	The cost of the purchased product. The following bounds apply: `cost` ≥ 0.	`15.2`
`sellingPrice`	double	The selling price of the purchased product. While optional, omitting this field may yield poor results when using a revenue-based exposure strategy. The following bounds apply: `sellingPrice` ≥ 0. Defaults to 1 if omitted.	`20.0`

Validate data

The Primer tool, used to validate priming data, is available to download.

Primer validator tool

To validate the priming data file, use the following command:

java -jar primer-validator.jar file-name.jsonl

Finalize data priming

Once the priming data file has been completed and successfully validated, the retailer must reach out to their designated Voyado service representative to finalize the data priming process.

Overview

Configuration

Catalog imports

Other imports

Site integration

Other integrations

Data priming syntax

Example

File specification

Validate data

Primer validator tool

Finalize data priming

​Data priming syntax

​Example

​File specification

​Validate data

Primer validator tool

​Finalize data priming

Data priming syntax

Example

File specification

Validate data

Finalize data priming