Skip to main content

Voyado Engage

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 to migrate your transactions via a file, either XML or CSV.

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

  • How far back should I go? (Voyado generally 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 containing irrelevant products.

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

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 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 see an example of the correct format by downloading this example CSV file.

Here is the example of the format in Excel.

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.