If you are migrating from an existing loyalty program and wish to retain your member data, Okendo Loyalty provides an importer as part of the Get Started assistant.
In this article, you’ll learn about:
How the importer works
File formats accepted by the importer
Creating tiers, as part of the import process
Error handling
Import Loyalty Data page
❗️ You will need to export your members (customers) from your existing provider, into a comma- separated value (CSV) file. Please refer to their instructions, on how to do this.
We support customer files from Yotpo, Loyalty Lion and Smile.
Alternatively, you can also create a generic CSV file, if you are with other providers. Simply add your member's details to it, save the file as a CSV and use it in the Import Loyalty Data page.
Importing loyalty data usually occurs during the program set up phase. To start the import process, go to Okendo Admin > Get Started. You will receive the Your Program page - the first step of the Okendo Loyalty onboarding assistant.
💡 This step will only appear if you have selected the option Do you have a current loyalty program? on the Your Program page. Also note that selecting this option, will disable Do you want to award points for past orders.
If you select the option Do you have a current loyalty program? on the Your Program page, you will be taken to the Import Loyalty Data page. You can Exclude Inactive Customers (e.g. records that have 0 points balance, 0 points spent and No Vip tier or the base VIP tier) to improve import efficiency.
Drag your file to the selected area or select Click to navigate to it.
💡If you have just installed the Okendo Loyalty app, you may be asked to enable additional Shopify permissions (see below). Follow the steps to do this.
Once you have enabled the required Shopify permissions, you will be asked whether your file contains VIP Tiers. If it does, select the toggle against Does your import include VIP tiers for members? and then Continue.
Add the required tier names and spend thresholds, to reach each tier.
❗️ It is important that the tier names in Okendo Loyalty match those in your CSV file, as the Import Loyalty Data page will validate these values and skip any it cannot match.
After you've created your tiers, select Save and Import. Okendo Loyalty will now validate each member record, in your import file, to ensure it can be imported without errors. Once it has completed this process, you should see the Member Import Preview screen. This will show you how many member records will be imported successfully and how many will not be imported at all.
After selecting Next, you will then be give an opportunity to view individual records, in particular those that will not import and the reasons for this. The reasons match the error messages in the import report. At this stage, you may choose to Import All (in which case, Okendo Loyalty will import those records it can). You will be required to correct erroneous records and import these later. Alternatively, you can cancel the process entirely and correct your import file.
💡 You may exit Loyalty at any time and this process will continue in the background. You will be sent an email, once the process has completed.
Generic CSV file format
The following are fields in the generic CSV file. Create and save a CSV with these fields as headers and use it when bringing in data from any other loyalty provider. It is mandatory for some fields to include a value per record, so please ensure you include these in the imported file.
Field name | Mandatory or Optional | Description |
Mandatory | The email address of the member | |
status | Mandatory | Some providers allow members to be in a non-enrolled (guest) or enrolled status in their program. This can be replicated in Okendo Loyalty, however the values are 'pending' (ie a guest) or 'enrolled'. |
firstName | Optional | First name of the member |
lastName | Optional | Last name of the member |
spent | Optional | Points spent to date, by the member |
balance | Optional | The points difference between earned and spent |
earned | Optional | Points earned to date, by the member |
expiry | Optional | The expiry date of points. The format required is YYYY-MM-DDTHH:MM:SS.sssZ |
programJoinDate | Mandatory when members status is 'enrolled'. Otherwise optional. | The date that the member enrolled in your program. The format required is YYYY-MM-DDTHH:MM:SS.sssZ |
vipTierId | Optional | A unique ID used to identify VIP Tiers |
vipTierName | Optional | The name of the VIP tier, that the member is currently on |
vipTierExpiry | Mandatory when vipTierName or vipTierId is provided. Otherwise optional. | The date where the member has to meet the tier spend limit, to remain on the current tier. The format required is YYYY-MM-DDTHH:MM:SS.sssZ |
vipTierEntered | Mandatory when vipTierName or vipTierId is provided. Otherwise optional. | The date the member entered their current tier. The format required is YYYY-MM-DDTHH:MM:SS.sssZ |
birthDay | Mandatory if birthMonth value is included. Otherwise optional | The specific day of the member's birthday. Can be any value between 1 - 31. Can be added to pending and enrolled members. |
birthMonth | Mandatory if birthDay value is included. Otherwise optional | The specific month of the member's birthday. Can be anything between 1 - 12, where each month is represented by it's corresponding value (eg October = 10, June = 6, Jan = 1). Can be added to pending and enrolled members. |
Generic CSV file format example
Importing customers after launch
If you forget, you can import member loyalty data, after your have launched your loyalty program. Go to Okendo Admin > Loyalty > Settings > Import.
The process is almost identical to the one embedded in program set up, albeit if you wish to utilize VIP tiers, you will be required to provision and enable them, prior to the import process. Refer to this article on how to do this.
The import report
You can view a report that shows the status of records in the CSV file (valid, invalid, imported and failed_import) as well as errors, explaining why a record was not imported. This report can be viewed, under Settings > Import/Export > Import History.
The following are possible error messages you may encounter:
Error Message | Cause of error and solution |
email is required | Ensure the 'email' header is present in the CSV file. |
<email> not a valid email address. | Ensure the email address for the row is a valid email. |
<email> duplicate email found. | This email already appears in the file, consolidate these rows. |
Status is required and must be one of enrolled or pending. | Ensure the 'status' header is present in the CSV file. |
Status must be one of enrolled or pending. | Ensure the values are either 'enrolled' or 'pending'. |
First name must be a non empty string. | Ensure there are no whitespace/hidden characters in the firstname column. |
Last name must be a non empty string. | Ensure there are no whitespace/hidden characters in the lastname column. |
Loyalty customer found with conflicting data. | This email belongs to another loyalty customer, this may be due to a customer merge from shopify. |
Loyalty customer found from another import. | This email was used in a previous loyalty importer and has not been removed. |
Balance must be a number. | Ensure the balance column contains only numeric characters. |
Earned must be a number. | Ensure the earned column contains only numeric characters. |
Spent must be a number. | Ensure the spent column contains only numeric characters. |
Spent must be 0 or a positive number. | Ensure the spent column contains only positive numbers or 0. |
Point integrity error earned - spent = balance. | The earned, spent and balance provided do not match up. Balance must be equal to the earned - spent. |
Balance cannot be greater than earned. This will result in a negative spend. | Ensure the balance is not greater than the earned. |
Expiry must be a valid date. | Ensure the date format provided matches YYYY-MM-DDTHH:MM:SS.sssZ |
Program join date must be a valid date. | Ensure the date format provided matches YYYY-MM-DDTHH:MM:SS.sssZ |
Only one of vipTierId or vipTierName can be specified. | There should only be a value in either vipTierId or vipTierName. Remove the vipTierId column and its data to resolve this. |
VIP tier is not supported for un-enrolled members. | Okendo Loyalty supports VIP tiers only for enrolled members. Mark the member as enrolled or remove the viptierName/vipTierId value |
VIP Tier ID cannot be mapped to a configured vip tier. | The vipTierId value does not match and Okendo Loyalty VIP Tier |
VIP Tier Name cannot be mapped to a configured vip tier. | The VIP Tier name does not match a configured tier. Check the spelling against the admin or update the VIP tier configuration to match. |
VIP Tier expiry date must be a valid date. | Ensure the date format provided matches YYYY-MM-DDTHH:MM:SS.sssZ |
VIP Tier expiry should not be in the past. | VIP tier expiry should be in the future or removed from the file. |
VIP Tier entered date must be a valid date. | Ensure the date format provided matches YYYY-MM-DDTHH:MM:SS.sssZ |
VIP Tier entry should not be in the future. | VIP tier entry cannot be in the future amend the date to when the customer attained this VIP tier. |
Birthday date invalid. | If the day of the birthday does not make sense. For example, entering birthDay 31 against birthMonth 6 (June) or birthDay 77 against birthMonth 12 (December). |
Birthday date invalid. Must provide values for both day and month. | When either birthDay or birthMonth are missing or nonsensical (eg "99" as birthMonth). |
What happens to members, once they are successfully imported?
A new member record is created in Okendo Loyalty, along with the appropriate points balance, status and VIP tier.
Where Okendo Loyalty can determine how long a member has been on their current VIP Tier (either using vipTierEntered or vipTierExpiry) and their spend to date on that VIP tier, it will continue tracking member spend in this context.
Where Okendo Loyalty cannot determine how long a member has been on their current VIP Tier (either using vipTierEntered or vipTierExpiry) and/or their spend to date on that VIP tier, it will default them to 12 months on the VIP Tier specified in the CSV import file. Members will stay on this tier for 12 months regardless of whether they have enough spend to progress to a higher tier. At the end of this period, Okendo Loyalty will calculate member spend, based on a rolling 12 month period, to determine if they remain on their current VIP Tier, progress to a higher VIP Tier or are demoted to a lower VIP Tier.
⚠️ NOTE
The Importer will keep processing records in the background until it has finished. You will be sent an email, once the process has completed.
What happens if records imported incorrectly?
If after the import process has completed, you recognize incorrect data against member records, you can delete you import (as long as you have not launched), by doing the following:
Go to Okendo Admin > Settings > Import/Export
Go to Import History and select
in the Delete column, against the relevant Loyalty Customers fileConfirm you want to delete the imported file by selecting Delete Import in the modal window
Once your file has been deleted, the file status will update with Deleted
If you have any specific questions or need further assistance, feel free to reach out to our support team.