Skip to main content
Importing points by file in the new points system works differently depending on if the Engage tenant is being configured for the first time, or if the Engage tenant is already up and running. The folders where the files are placed have similar names, and these are easily confused, so take care to put them in right place depending on which of the two cases apply to you. Each import is done by running a different scheduled job. There is also a difference in how contacts are identified in the two imports. The initial setup import will allow you to choose from a range of key types and keys (for example “memberNumber”), while in the ongoing points import you’ll need to use the internal contact ID.

​
Case 1 - When setting up tenant

Your CSV or XML file, formatted in the correct way, should be placed in this FTP folder: 
integration\pointTransactionImport
The job to run is ImportHistoricalPointsFromFileJob which will validate and import historical point files and store them in the database.
https://mintcdn.com/voyado/-QD3xMpfEY3BtcMt/icons/developer-link.png?fit=max&auto=format&n=-QD3xMpfEY3BtcMt&q=85&s=92be9e7202a0fc63f959e3f367cc7e32

How to import points history
Example with ValidTo
Key;KeyType;PointDefinitionId;Amount;TransactionType;TransactionDate;CreatedOn;ValidTo;CreatedBy;Description;Source;ExpireAfterMonthsInactive
ABC123;MemberNumber;1;100.5;Purchase;2023-01-01T08:14:00.829Z;2023-01-01T08:14:00.829Z;2024-01-01T08:14:00.829Z;test@voyado.com;Test description;;
ABC123;MemberNumber;1;100;Purchase;2023-02-01T08:14:00.829Z;2023-02-01T08:14:00.829Z;2024-02-01T08:14:00.829Z;test@voyado.com;Test description1;;
ABC123;MemberNumber;1;-100;Return;2023-03-01T08:14:00.829Z;2023-03-01T08:14:00.829Z;2024-03-01T08:14:00.829Z;test@voyado.com;Test description2;;
Example with ExpireAfterMonthsInactive
Key;KeyType;PointDefinitionId;Amount;TransactionType;TransactionDate;CreatedOn;ValidTo;CreatedBy;Description;Source;ExpireAfterMonthsInactive
ABC123;MemberNumber;1;100.5;Purchase;2023-01-01T08:14:00.829Z;2023-01-01T08:14:00.829Z;;test@voyado.com;Test description;;12
ABC123;MemberNumber;1;100;Purchase;2023-02-01T08:14:00.829Z;2023-02-01T08:14:00.829Z;;test@voyado.com;Test description1;;12
ABC123;MemberNumber;1;-100;Return;2023-03-01T08:14:00.829Z;2023-03-01T08:14:00.829Z;;test@voyado.com;Test description2;;6
For the setting-up case, it’s important that no other point calculation are going on at the same time, such as points being added by API or automations. This import must be the only point job that is running. For the second job (see Case 2 below) it’s not a problem to have several points calculations going at once.
Always use . (a dot) for non-integer amounts in files. Using , (a comma) or anything else will cause an error. For example “10.50” is correct while “10,50” is not correct.

​
Case 2 - When tenant is already active

When the tenant is already active, another job is used. This is a bit slower but more safe and ensures that no data is modified incorrectly. Your CSV or XML file, formatted in the correct way, should be placed in this FTP folder: 
integration\pointTransaction
CSV files in these imports should have a maximum of 2000 rows.
Multiple files can be imported in the same run. The job to run is ImportPointsFromFileJob and this validates, reads and imports the points.

​
Procedure

Create a file, and add it to the folder specified. Then run the scheduled job mentioned in the information. When the job runs it will handle all files added to the folder. The import will add points in the same way as points are usually added in the system. To have the correct balance for point accounts after the import, the Update Balance job needs to run.

​
Properties used

​
ContactId
guid
Must be an existing, not deleted, approved contact of type Member.
​
Amount
decimal
Cannot be 0.
​
DefinitionId
integer
Definition must exist in Engage.
​
TimeStamp
datetimeoffset
Can be NULL. Defaults to UTC Now Offset.
​
Source
string
required
Should not be empty. If points-based member levels are used, and you want to exclude some points, only use these predefined values:
  • Purchase
  • Adjustment
  • BonusBalanceAdjustment
  • Return
  • RewardVoucher
  • UpdateBalance
  • BonusPromotion
  • BonusPromotionReturn
  • Automation
​
Description
string
Should not be empty.
​
ValidFrom
datetimeoffset
Can be excluded from the file. Defaults to UTC Now Offset.
​
ValidTo
datetimeoffset
Can be excluded from the file. Defaults to the expiry rules set up for the tenant (for example, 12 months rolling expiry). Cannot be combined with a value in ExpireAfterMonthsInactive. One or the other may be used, or neither — never both in the same row.
​
ExpireAfterMonthsInactive
integer
Can be excluded from the file. Defaults to the expiry rules set up for the tenant (for example, “6” months). Must be higher than 0. Cannot be combined with a value in ValidTo. One or the other may be used or neither, but never both in the same row. Only to be used on active transactions. Transactions that have already expired must have an expiry date in ValidTo and no value in this field. Only applies if using the expiry method “Contact inactive”.
These settings currently only work with predefined legacy fields that can translate to the new predefined ones. If the tenant setting for expiration is correctly set up AND the value of validTo or expireAfterMonthsInactive matches that expiration setting, these fields can both be set to blank and Engage will add the values based on what is set up in these expiration settings.
Example with ValidTo
ContactId;DefinitionId;Amount;ValidFrom;ValidTo;Description;Source;ExpireAfterMonthsInactive;TimeStamp
a20fe4f3-5cca-491f-ba2a-e6f04ff0d4d8;1;100.54;2023-01-01T08:14:00.829Z;2024-01-01T08:14:00.829Z;Test description;Purchase;;2023-01-01T08:14:00.829Z
db9b702c-9087-4c22-82a3-f133771a6c5f;1;100;2023-02-01T08:14:00.829Z;2024-02-01T08:14:00.829Z;Test description1;Adjustment;;2023-02-01T08:14:00.829Z
1dc891cb-ae93-492e-9d4d-aa985f3d781d;1;-100;2023-03-01T08:14:00.829Z;2024-03-01T08:14:00.829Z;Test description2;Return;;2023-03-01T08:14:00.829Z
Example with ExpireAfterMonthsInactive
ContactId;DefinitionId;Amount;ValidFrom;ValidTo;Description;Source;ExpireAfterMonthsInactive;TimeStamp
a20fe4f3-5cca-491f-ba2a-e6f04ff0d4d8;1;100.54;2023-01-01T08:14:00.829Z;;Test description;Purchase;12;2023-01-01T08:14:00.829Z
db9b702c-9087-4c22-82a3-f133771a6c5f;1;100;2023-02-01T08:14:00.829Z;;Test description1;Adjustment;12;2023-02-01T08:14:00.829Z
1dc891cb-ae93-492e-9d4d-aa985f3d781d;1;-100;2023-03-01T08:14:00.829Z;;Test description2;Return;6;2023-03-01T08:14:00.829Z

​
Validation errors

Here are the validations errors you might get and what they mean.
PointTransaction file import missing mandatory columns, will skip file: [FileName]
Here, the import file does not define all fields used. The file will be skipped and the error logged.
Missing contactId: [contactId] In data that was not valid: [[notAccepted]]
The contact ID used does not represent an existing, not-deleted and approved contact of type “Member”. The file line will be skipped and the error logged.
Missing PointDefinitionId: [[definitionIds]] In data that was not valid: [[notAccepted]]
Definition ID does not have a corresponding point definition in the database. File line will be skipped and the error logged.
Other error message: [[error]] In data that was not valid: [[notAccepted]]
Source does not have a value. File line will be skipped and the error logged.
Other error message: [[error]] In data that was not valid: [[notAccepted]]
Description does not have a value. File line will be skipped and the error logged.
No error message
Points value given is zero. No points added, no logs or errors created.
No error message
Point account with the specified definition does not exist, or exists several times. Creation of new account is not working as intended. An exception is created.
Other error message: [[error]] In data that was not valid: [[notAccepted]]
The value ExpireAfterMonthsInactive is negative. File line will be skipped and the error logged.
Other error message: [[error]] In data that was not valid: [[notAccepted]]
The value ExpireAfterMonthsInactive is 0. File line will be skipped and the error logged.
Other error message: [[error]]
The value ExpireAfterMonthsInactive has a valid integer value and ValidTo also has a date value. File line will be skipped and the error logged.