Order history¶

Data priming, or priming, is the addition of a retailers order history, the historical sales statistics, into Voyado Elevate. The use of historical sales statistics enables Elevate to more quickly improve results and content for visitors.

In order for Elevate to process the order history, it must provided as an XML file with UTF-8 encoding, compliant with the file syntax for data priming.

Priming is not a mandatory integration activity, but highly recommended. If priming is to be done for a site, it must be performed at the end of an Integration before go-live. Priming is only to be performed once, and 3 months' worth of orders are recommended to be included, regardless of the number of orders received during that period.

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 example will add two orders with a total of three products as priming data.

<?xml version="1.0" encoding="UTF-8"?>
<orders>
    <order>
        <time>2017-10-14T12:00:00+01:00</time>
        <customer_key>d9528030-509c-4e0f-b585-7168f1e9feca</customer_key>
        <market>UK</market>
        <lines>
            <line>
                <product_key>P_555452-0446_UK</product_key>
                <variant_key>V_555452-0446_1_UK</variant_key>
                <quantity>3</quantity>
                <unit_cost>2.2</unit_cost>
                <unit_selling_price>5.5</unit_selling_price>
            </line>
        </lines>
    </order>
    <order>
        <time>2017-10-14T12:00:05+01:00</time>
        <customer_key>e030d954-b585-280f-509c-68f171fee9ca</customer_key>
        <market>UK</market>
        <lines>
            <line>
                <product_key>P_335975-0444_UK</product_key>
                <variant_key>V_335975-0444_3_UK</variant_key>
                <quantity>1</quantity>
                <unit_cost>3.5</unit_cost>
                <unit_selling_price>4.2</unit_selling_price>
            </line>
            <line>
                <product_key>P_133449-0338_UK</product_key>
                <quantity>2</quantity>
                <unit_cost>5.1</unit_cost>
                <unit_selling_price>8.5</unit_selling_price>
            </line>
        </lines>
    </order>
</orders>

File specification¶

A data file contains a root element, orders, with one or more order elements. An order includes one or more products that have been purchased and its related purchase data. The order elements must be in ascending chronological order, i.e. oldest first/newest last.

The following elements are allowed in a priming data XML-file.

Name	Type	Description	Example
`orders`	Root element	The root element of the priming data file. It can only hold `order` elements as child elements. Required element.	N/A
`order`	Container element	The element containing all information about a purchase. Parent element is `orders`. Required element.	N/A
`time`	time_point	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`
`customer_key`	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.	`Sweden`
`lines`	Container element	The element containing the `line` elements. Parent element is `order`. Required element.	N/A
`line`	Container element	The element containing all elements related to the purchase of a specific product in an order. Required element.	N/A
`product_key`	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`
`variant_key`	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`
`unit_cost`	double	The cost of the purchased product. The following bounds apply: `unit_cost` ≥ 0.	`15.2`
`unit_selling_price`	double	The selling price of the purchased product. The following bounds apply: `unit_cost` ≥ 0. Defaults to 1 if omitted.	`20.0`

Validate data¶

The Primer tool used to verify priming data is available for download for Voyado Elevate customers.

The priming data file is validated with the Primer tool and the following command.

java -jar primer.jar validate file-name.xml

Finalise data priming¶

When the priming data file is complete and validated a retailer must contact their appointed Voyado service personnel to finalise the data priming process.