Import historical transactions
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
In Engage, a transaction is defined as when a customer visits a physical or online store and purchases (or returns) one or more items. The transaction contains metadata -- such as the transaction's unique ID, the store's ID, the timestamp -- plus the data for each individual item purchased or returned (line items). The transaction's data is then sent to the endpoint called /receipts to be saved so you might see this term turning up in the API.
Prerequisites for importing transactions
Here are some important things to confirm before you import your historical transactions.
All contacts referred to in your file must already exist in Engage before the import of transactions is started. If a contact does not exist, the transaction data connected to them will be ignored.
Likewise, all stores referred to in the file must already exist.
If a transaction already exists in Engage then the imported transaction data will be ignored. No updates will be done to the existing transaction.
Don't exceed 20 000 receipts per file. This is not a hard limit but a strong recommendation. Large files can make the server very slow and risk causing a timeout. Note that the number refers to transaction lines and not transactions.
If the import is done in CSV format the columns should be separated by semicolons and not by commas.
You can’t map transactions 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.
Warning
When using the Data Validator for transactions be aware that it will NOT detect missing stores or contacts, because the validator is not directly connected to any specific Engage environment. The client should ensure that the stores referenced exist in Engage as do the contacts. However, when importing that file into Engage, those "bad" lines will just be skipped and logged as errors.
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 transaction
Item rows are the transactions on that transaction
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 | string | Valid options: contactId, memberNumber, socialSecurityNumber, mobilePhone, externalId, email | |
*contactType | member | string | Definition of which contact type to match the transaction with |
*uniqueReceiptId | 2287565954-25 | string | Needs to be a unique number for each transaction |
*receiptNumber | 2287565954 | string | The transaction 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 transaction 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 transaction 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 |
Warning
Unusual characters might give an error during a CSV validation or import. One of these is the character " (ASCII code Alt 0148). If your import fails for unknown reasons, check for this and other unusual characters.
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.