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.

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 key conventions

Market identifiers and product key conventions must be consistent across the data feed, 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¶

File example¶

The following JSONL example will add 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}]}

Formatted JSON example to illustrate its structure.

{
  "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. Required element.	`2017-10-14T12:00:00+01:00`
`customerKey`	string	The visitor id. A SHA256 hash if the visitor was signed in, otherwise a UUID / GUID.	`5G7HJ...R77T1`
`market`	string	The Elevate market where the purchase was performed. Must match the market used in the data model. Required element.	`UK`
`lines`	array	The element containing the `line` elements. Required element.	N/A
`line`	object	The element containing all elements related to the purchase of a specific product in an order. Required element.	N/A
`productKey`	string	The unique key of the purchased product. Must be the same as keys used for products in the data feed. Required element.	`shirt_79709`
`variantKey`	string	The unique variant key of the variant. Must be the same as keys used for variants in the data feed. Required element.	`shirt_79709_M`
`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 for download for Voyado Elevate customers.

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

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

Finalise 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.