> ## Documentation Index
> Fetch the complete documentation index at: https://product-discovery.developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Data priming order history
> How to add historical order data to Voyado Elevate through data priming, covering the JSONL file specification and validation with the Primer tool.
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.
```jsonl JSONL icon="code" theme={null}
{"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}]}
```
```json JSON (only for demonstration purposes) icon="code" expandable theme={null}
{
"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](https://en.wikipedia.org/wiki/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](/elevate/docs/integration/essentials/catalog-concepts). | `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](/elevate/docs/integration/catalog-imports/catalog-imports). | `shirt_79709` |
| `variantKey`\* | string | The unique variant key of the variant. Must be the same as keys used for variants in the [catalog import](/elevate/docs/integration/catalog-imports/catalog-imports). | `shirt_79709_M` |
| `customerKey` | string | The visitor ID. A SHA256 hash if the visitor was signed in, otherwise a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) 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.
To validate the priming data file, use the following command:
```bash icon="terminal" theme={null}
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.