Emarsys Loyalty provides an option to migrate the contacts from your existing loyalty program to the new one in the Loyalty add-on.
The following parameters can be migrated to the new program:
- Member status:
- Original join date of the contact
- The tier of the contact
- Member points:
- Status points (points to advance to the next tier)
- Spend/balance points (points to redeem)
- Timestamp of the expiration date for the points
- Voucher data:
- Contact identifier
- Voucher name and other details
- Voucher code
On the day of migration, send a .csv file with below mentioned columns to your Implementation Consultant so the Loyalty team can migrate your contacts and their data.
In the .csv file use commas as column separators.
If a field value contains comma, then it needs to be double quoted. For example, the following voucher name needs to be sent like this: "Special voucher for moms, kids."
CSV file specifications for contacts
-
This
.csvfile has to be sent with all contacts to be migrated.
The .csv file must contain the following columns in this specific order:
| CSV column header | Description | Type |
|---|---|---|
userId |
The unique contact identifier. This has to be the same as in the uploaded sales data. | string |
shouldJoin |
Enter TRUE into this column for each customer. |
string |
joinDate |
The original date the user joined the old loyalty program. |
integer (in UNIX timestamp format, milliseconds) |
tierName |
The name of the tier to be assigned to your contact. It has to be written exactly how it is defined in the Emarsys Loyalty plan settings. Without a tier name, the contact will be placed automatically in the bottom tier (tier 1). |
string |
tierEntryAt |
Leave empty |
|
tierCalcAt |
Leave empty |
|
shouldReward |
This parameter is used by migration scenarios. When set to |
string |
Loyalty will add the user into the tier on the day of migration. If the tier configuration is 12 months, then the 12 months are counted from the migration date.
If you sent us status points in the points file that will put the member into a higher tier than the tier name you sent in the contact file, Loyalty System will upgrade the member to the tier according to the status points.
CSV file specification for points
- This .csv file should include only contacts from the contact migration file who need to receive points. Contacts for whom no points should be assigned must not be included in the file.
- Do not use decimal separators (comma, dot) in your numbers. E.g. do not send 1.000 or 1,000 but send 1000.
The .csv file must contain the following columns in this specific order:
| CSV column header | Description | Type |
|---|---|---|
userId |
The unique contact identifier. This has to be the same as in the uploaded sales data. | string |
pointsToSpend |
The amount of balance points that can be used for redemption by the member. The validity period of the points will start from the moment the contact is migrated. |
positive integer |
statusPoints |
The amount of Status points of the members that determine their tier. |
positive integer |
cashback |
The amount of cashback available for the member. It is only relevant for Spend & Benefits plans. Otherwise, leave empty. | positive float |
allocatedAt |
Leave empty |
|
expireAt |
The expiration date of the points. If you want Loyalty to calculate expiration date, then leave this column empty, and set column setPlanExpiration to TRUE. |
integer (in UNIX timestamp format, milliseconds) |
setPlanExpiration |
If you want Loyalty to set the expiration according to the plan settings, then put TRUE here.Otherwise, use the expireAt column and tell us when points expire, and sent the value of this column to FALSE. |
string |
reason |
An optional description for Loyalty admins in Member Profiles for the given activity. Loyalty members are not able to see this. | string |
title |
The title of the activity/description that the user will see in the Wallet, and in Member Profiles. |
string |
description |
This is the description that contacts see for a specific activity in their Wallet. To use this, you also need to set the |
string |
All points are added to the user with the timestamp of the migration.
Example
For example, this customer may start the new plan as a silver member with 540 status points (points from previous plan):
If you keep the statusPoints field blank, the status points of the member will be zero and the member will be distributed into the tier defined in column: tierName.
Make sure to send the points data in the migration file including data up to midnight before the migration date.
CSV file specification for vouchers
Loyalty allows you to migrate the current voucher codes of your users into the Emarsys loyalty system, so that they can continue to see and use the same codes.
For the voucher migration we need the fields below:
|
CSV column header |
Description |
Type |
|---|---|---|
userId |
The contact identifier for Loyalty and Smart Insight, for example, email. | string |
externalId |
The hashed userId, this equals the loyaltyId field in Emarsys contact database.Value fulfilment is optional (can be left empty), or it can be used instead of the userId. |
string |
voucherType |
To define if the voucher is one-time or multi, use use one of these values: one_time / yearly. | string |
voucherName |
The name of the voucher as it should appear in the Wallet and the API. | string |
iconName |
The icon that should appear for the voucher. As for the default icon, use this string: basket-colors-1. *
|
string |
code |
The voucher code itself. | string |
expiration |
The validity deadline of the voucher. After this date, the voucher will vanish from the Wallet and the API. | integer (in UNIX timestamp format, milliseconds) |
*If you want to have a different icon, please ask your Implementation Consultant to upload your desired icon into the loyalty system. You will be provided with the icon name to be used inside the file.
Important for migration: The same voucher code can be given only once to the same user, but two different users can get the same voucher code.
After migration, the voucher will appear in the Wallet as the following (example: 10$ cashback):
Migration best practices
After the migration process is finished, enable sales data import under Loyalty Configuration > Sales Data Import, with the migration date as the start date. This way, Loyalty will only import sales data for which points were not given.
In case you want to check sales data prior migration, you can activate data import, but turn it off before migration and update the Sales Data Start date to after the migration to specify the date of purchase to be imported.