Import historical receipts

When getting started with Voyado Engage, historical transactions are valuable as a way to gain insights and allow you to try out more advanced segmentation. However, the Engage API should never be used to perform operations on a large number of transactions simultaneously (a so-called bulk update). For doing this, our recommended approach is to migrate your transactions via a file, either as XML or CSV.

The key questions you need to answer before a file-based migration are:

How far back should I go? (Voyado usually recommends 18 months)
Do I plan to add additional product data to the transactions?
Does my data include transactions that aren’t relevant? For example, those of deleted contacts or with irrelevant products

Any such migration needs to be planned with your Voyado team. Migrations are handled separately from automated imports.

Note

It's useful to think of a receipt as being composed of its own data and also one or more individual transactions.

Prerequisites for importing transactions

Here are some important things to confirm before you import your historical receipts.

All contacts referred to in your file must already exist in Engage before the import of receipts is started. If a contact does not exist the receipt data connected to them will be ignored.
Likewise, all stores referred to in the file must already exist.
If a receipt already exists in Engage then the imported receipt data will be ignored. No updates will be done to the existing receipt.
If the import is done in CSV format the columns should be separated by semicolons and not by commas.
You can’t map receipts with more than one matchKeyType per file. If a file contains more than one matchKeyType mapping then they should be split into several files.
For dates, Engage requires the data formatted as ISO8601 with Time zone designators.

Validation of your files

Validation of your CSV or XML files is an important step before importing. It ensures your data has the correct format and will greatly reduce the possibility of errors and lost data. Use the Engage validation service to make sure your files are in the correct format. You can read more about the service and find a link to it here.

File import location

When your files have been prepared and approved on your side and by your Voyado team, they will need to be placed in a designated folder on the Engage FTP for the actual import to happen. Read more about that step here.

CSV file import

You can download CSV and Excel examples on the example files page.

There are two kinds of rows in a CSV import, header rows and item rows.

Header rows hold information about the receipt
Item rows are the transactions on that receipt

Whether a row is a header or an item is determined by the the field called header which is 1 for header rows and 0 for item rows.

Header fields

Fields marked with * are mandatory.

Field	Example	Type	Description
*matchKey	doe@voyado.com	string	A value to match against the specified customerKeyType and contactType
*matchKeyType	email	string	Valid options: contactId, memberNumber, socialSecurityNumber, mobilePhone, externalId, email
*contactType	member	string	Definition of which contact type to match the receipt with
*uniqueReceiptId	2287565954-25	string	Needs to be a unique number for each receipt
*receiptNumber	2287565954	string	The receipt number you segment on in Voyado. Does not have to be unique.
*createdDate	2020-09-06T15:55:54+01:00	datetime	Date and time when the receipt was created formatted according to ISO 8601 with Time Zone designator
*storeExternalId	930	string	The unique id for the store where the purchase was made
*currency	EUR	currency	The currency code according to ISO 4217 for the currency that the customer paid in (local currency)
*exchangeRateToGroupCurrency	10.00	decimal	The exchange rate to the group currency set in Voyado. Default value is 1.00
*totalGrossPrice	200.00	decimal	The total price paid by he customer including VAT. A punctation(.) is always used as decimal separator. Default is 0
paymentTypeType	creditcard	string	Pre-defined values can be set: “card”, “cash”, “creditcard”, “bonuscheck”, “swish”, “klarna”. If your value does not match one of the above, it will be categorized as custom: “custom: [value]”(max 245 characters)
paymentTypeValue	200.00	decimal	Amount in decimal format. Can't be empty.
paymentTypeDescription	Mastercard	string	A descriptive text (max 255 characters)
*header	1	bit	Should always have value 1 if it is a receipt header

Item row fields

Fields marked with * are mandatory.

Field	Example	Type	Description
*type	PURCHASE	string	A line item can either be of type PURCHASE or RETURN
*sku	12345-1	string	Store keeping unit of the article
*articleName	Denim white	string	Article name
articleGroup	Jeans	string	The highest level of the article group categorization to segment on in Voyado
*quantity	1	integer	The number of units sold in the specific line item. If it is a RETURN then it must be a negative value.
*grossPaidPrice	200.00	decimal	The total price of units in the specific line item including VAT and the discount withdrawal
articleNumber	12345	string	Article number
awardsBonus	true	boolean	If the line item included for reward calculation or not. Default value is true if the field is not defined
taxAmount	40.00	decimal	The total VAT of the units in the line item. Default is 0
taxPercent	25.00	decimal	The VAT percentage of the unit. Default is 0
discount	-200.00	decimal	Discount value in local currency. Should always be negative. Segmentation on discounts is possible in Voyado. Default is 0
spare[1-10]		string	Additional data for the line item
datespare[1-5]	2020-09-06T15:55:54+01:00	datetime	Additional datetime data for the line item
*header	0	bit	Must have value 0 if it is a line item row

XML file import

If your import data is in XML format, it must have the following header:

<?xml version="1.0" encoding="UTF-8"?>
<transactions xmlns="http://voyado.Schemas.ImportReceipts" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

A complete XML file for importing transactions will look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<transactions xmlns="http://voyado.Schemas.ImportReceipts" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<transaction LineNumber="0" LinePosition="0">
		<contact LineNumber="0" LinePosition="0">
			<matchKey>120200000044</matchKey>
			<matchKeyType>memberNumber</matchKeyType>
			<contactType>Member</contactType>
		</contact>
		<uniqueReceiptId>7a5f0140-c50f-11eb-8984-5b9396574b87</uniqueReceiptId>
		<receiptNumber>7a5f0140-c50f-11eb-8984-5b9396574b87</receiptNumber>
		<createdDate>2020-08-06T08:29:40+02:00</createdDate>
		<storeExternalId>8202</storeExternalId>
		<currency>SEK</currency>
		<exchangeRateToGroupCurrency>1</exchangeRateToGroupCurrency>
		<totalGrossPrice>102</totalGrossPrice>
		<paymentMethods>
		      <paymentMethod>
		        <type>bonuscheck</type>
		        <description>20kr bonuscheck</description>
		        <value>20.00</value>
		      </paymentMethod>
		      <paymentMethod>
		        <type>card</type>
		        <description>card</description>
		        <value>82.00</value>
		      </paymentMethod>
		</paymentMethods>
		<items>
			<item LineNumber="1" LinePosition="0">
				<type>PURCHASE</type>
				<sku>A123</sku>
				<quantity>8</quantity>
				<grossPaidPrice>712</grossPaidPrice>
				<taxAmount></taxAmount>
				<taxPercent></taxPercent>
				<articleNumber>ArticleNumber123</articleNumber>
				<articleName>ArticleName 1</articleName>
				<articleGroup>Group 1</articleGroup>
				<discount>0</discount>
				<awardsBonus>false</awardsBonus>
				<spare1>Spare 1</spare1>
				<spare2>Spare 2</spare2>
				<spare3>Spare 3</spare3>
				<spare4>Spare 4</spare4>
				<spare5>Spare 5</spare5>
				<spare6>Spare 6</spare6>
				<spare7>Spare 7</spare7>
				<spare8>Spare 8</spare8>
				<spare9>Spare 9</spare9>
				<spare10>Spare 10</spare10>
			</item>
			<item LineNumber="2" LinePosition="0">
				<type>PURCHASE</type>
				<sku>A123</sku>
				<quantity>4</quantity>
				<grossPaidPrice>92</grossPaidPrice>
				<taxAmount></taxAmount>
				<taxPercent></taxPercent>
				<articleNumber>ArticleNumber123</articleNumber>
				<articleName>ArticleName 1</articleName>
				<articleGroup>Group 1</articleGroup>
				<discount>0</discount>
				<awardsBonus>false</awardsBonus>
				<spare1>Spare 1</spare1>
				<spare2>Spare 2</spare2>
				<spare3>Spare 3</spare3>
				<spare4>Spare 4</spare4>
				<spare5>Spare 5</spare5>
				<spare6>Spare 6</spare6>
				<spare7>Spare 7</spare7>
				<spare8>Spare 8</spare8>
				<spare9>Spare 9</spare9>
				<spare10>Spare 10</spare10>
			</item>
			<item LineNumber="3" LinePosition="0">
				<type>PURCHASE</type>
				<sku>A123</sku>
				<quantity>10</quantity>
				<grossPaidPrice>250</grossPaidPrice>
				<taxAmount></taxAmount>
				<taxPercent></taxPercent>
				<articleNumber>ArticleNumber123</articleNumber>
				<articleName>ArticleName 1</articleName>
				<articleGroup>Group 1</articleGroup>
				<discount>0</discount>
				<awardsBonus>false</awardsBonus>
				<spare1>Spare 1</spare1>
				<spare2>Spare 2</spare2>
				<spare3>Spare 3</spare3>
				<spare4>Spare 4</spare4>
				<spare5>Spare 5</spare5>
				<spare6>Spare 6</spare6>
				<spare7>Spare 7</spare7>
				<spare8>Spare 8</spare8>
				<spare9>Spare 9</spare9>
				<spare10>Spare 10</spare10>
			</item>
			<item LineNumber="4" LinePosition="0">
				<type>PURCHASE</type>
				<sku>A123</sku>
				<quantity>3</quantity>
				<grossPaidPrice>300</grossPaidPrice>
				<taxAmount></taxAmount>
				<taxPercent></taxPercent>
				<articleNumber>ArticleNumber123</articleNumber>
				<articleName>ArticleName 1</articleName>
				<articleGroup>Group 1</articleGroup>
				<discount>0</discount>
				<awardsBonus>false</awardsBonus>
				<spare1>Spare 1</spare1>
				<spare2>Spare 2</spare2>
				<spare3>Spare 3</spare3>
				<spare4>Spare 4</spare4>
				<spare5>Spare 5</spare5>
				<spare6>Spare 6</spare6>
				<spare7>Spare 7</spare7>
				<spare8>Spare 8</spare8>
				<spare9>Spare 9</spare9>
				<spare10>Spare 10</spare10>
			</item>
			<item LineNumber="5" LinePosition="0">
				<type>RETURN</type>
				<sku>A123</sku>
				<quantity>-4</quantity>
				<grossPaidPrice>-28</grossPaidPrice>
				<taxAmount></taxAmount>
				<taxPercent></taxPercent>
				<articleNumber>ArticleNumber123</articleNumber>
				<articleName>ArticleName 1</articleName>
				<articleGroup>Group 1</articleGroup>
				<discount>0</discount>
				<awardsBonus>false</awardsBonus>
				<spare1>Spare 1</spare1>
				<spare2>Spare 2</spare2>
				<spare3>Spare 3</spare3>
				<spare4>Spare 4</spare4>
				<spare5>Spare 5</spare5>
				<spare6>Spare 6</spare6>
				<spare7>Spare 7</spare7>
				<spare8>Spare 8</spare8>
				<spare9>Spare 9</spare9>
				<spare10>Spare 10</spare10>
			</item>
		</items>
	</transaction>
</transactions>

It's important to note that when sending paymentMethod in the XML you need to include all three elements, type, value and description, as seen in the example above.

Important

The mandatory fields in an XML import are the same as in the CSV import. See the tables above.

In this section:

Voyado Engage