Use a CSV file to add new members to Loyalty, or to update members you imported before. You can import during onboarding, or at any time from the Members area. Loyalty emails you when the import is finished.
If your store is on Shopify, you don't need to import. Loyalty gets your members when you sync your Shopify customers.
How importing works
Loyalty matches each row in your file to a member by externalId. This is the ID your own system uses for that customer.
If no member has that externalId, Loyalty creates a new member.
If a member has that externalId, Loyalty replaces their details with the values in your file.
Loyalty doesn't match by email address or mobile number, so you can change these in a later import.
Updating existing members
When you update a member, every column in your file replaces what Loyalty holds for them. An empty cell clears the current value.
However, pointsBalance works differently:
Leave it empty to keep the member's current points balance.
Enter a value to replace their points balance. This includes 0.
Import an older file
If you import an old file with points balances filled in, those balances replace the current ones. Any points members earned since then are lost.
Change enrollment status
If you change a member's enrollmentStatus from Enrolled to NotEnrolled, their points are removed.
What imported members get
Members you import as Enrolled can earn points straight away. Imported members don't get the Welcome email or any points for joining, such as the Welcome bonus.
Rows marked NotEnrolled or Unenrolled are added as customers, not members. They have no points activity.
Before you start
You can't undo an import, and you can't delete members after you import them.
Loyalty checks that each value is in the right format, but not that the value is correct. We don’t check whether email addresses and mobile numbers are valid, so check them before you import.
Every row needs an externalId. Use the same ID your store uses for that customer. If the IDs don't match, the member can't see their points balance or redeem rewards in the loyalty widget.
If a customer's externalId changes, your next import creates a new member for them.
Each email address and mobile number can belong to only one member. Two members can't share an email address or mobile number, even if they have different externalIds.
Prepare your CSV file
Start from our CSV template so your file is in the right format. Download our CSV template from the section Example CSV file on this page, or select Download CSV template on the Import members page.
Your file must:
Be a CSV file of up to 20 MB.
Have a header row with the column names from the template.
Have an externalId in every row, plus an email address, a mobile number, or both. All other columns are optional.
Values are imported exactly as you type them, so remove any extra spaces.
Column | Required | Accepted values | Example |
externalId | Yes | Text, up to 255 characters. Use the ID your store uses for this customer. | ext-001 |
firstName | No | Text, up to 255 characters | Alice |
lastName | No | Text, up to 255 characters | Smith |
No | Text, up to 255 characters | ||
telephoneNumber | No | The member's mobile number, in international format with a plus sign | +447700900001 |
birthday | No | A date in YYYY-MM-DD format | 1990-01-15 |
emailMarketingConsentState | No | NotSubscribed: never subscribed. Subscribed: subscribed now. Unsubscribed: subscribed before, then opted out. | Subscribed |
smsMarketingConsentState | No | NotSubscribed: never subscribed. Subscribed: subscribed now. Unsubscribed: subscribed before, then opted out. | NotSubscribed |
enrollmentStatus | No | Enrolled: a member of your loyalty program. NotEnrolled: never joined. Unenrolled: joined before, then left. | Enrolled |
tags | No | Tags separated by semicolons | vip;newsletter |
pointsBalance | No | A positive number. To keep a member's current points balance, leave it empty. | 100 |
Example CSV file
Download loyalty-member-import-template.csv.
externalId,firstName,lastName,email,telephoneNumber,birthday,emailMarketingConsentState,smsMarketingConsentState,enrollmentStatus,tags,pointsBalance
ext-001,Alice,Smith,alice.smith@example.com,+447700900001,1990-01-15,Subscribed,NotSubscribed,Enrolled,vip;newsletter,100
ext-003,Carol,White,carol.white@example.com,,,Subscribed,Subscribed,NotEnrolled,store-a,
ext-004,Dave,Brown,dave.brown@example.com,+447700900004,2000-12-01,Unsubscribed,NotSubscribed,Enrolled,,0
Import members from the Members page
In Loyalty, go to Members.
Select Import members.
Drag your CSV file into CSV file, or select choose file.
In Email address to notify, enter the email address that should receive the import results.
Select Import members.
While the import runs, a banner in Members shows that it's in progress.
Import members during onboarding
In Loyalty, on the Import your members step, select Download example CSV if you need the template.
Drag your CSV file into CSV file, or select choose file.
In Email address to notify, enter the email address that should receive the import results.
Select Next.
To import later, select Skip. You can import from Members at any time.
Check your import
Loyalty emails the address you entered every time an import finishes, whether it worked or not.
To see your past imports, select the Account icon, the go to Settings > Member import history. For each import, you can see the import date, its status, and how many rows were added, updated and skipped.
Status | What it means |
In progress | The import is still running. |
Complete | Every row was imported. |
Partly complete | Some rows were imported and some were skipped. |
Failed | No rows were imported. |
To check whether a particular member was imported, search for their email address or mobile number in Members.
If rows are skipped or the import fails
Loyalty checks each row on its own. If a row has a value in the wrong format, Loyalty skips that row and imports the rest of the file.
The email you get tells you what happened and what to do next. It doesn't say which rows were skipped or why.
What happened | What to do | |
Import complete | Every row was imported. | Nothing. Go to Members to see your members. |
Partly complete | Some rows were skipped because of the format of your file. | Compare your file with the CSV template, fix anything that doesn't match, and import the whole file again. |
Failed because of your file | No rows were imported because of the format of your file. | Compare your file with the CSV template, fix anything that doesn't match, and import the file again. |
Failed because of a system error | No rows were imported because of a problem on our side. | Import the same file again. |
Stopped partway | Some rows were imported before a problem on our side. | Import the whole file again. |
When you import the whole file again, Loyalty updates the members it already imported. It doesn't create duplicates.
If importing again doesn't work, contact support.
Troubleshoot your import file
If rows are skipped, check that:
Every row has an externalId.
Consent and enrollment values match the accepted values exactly. For example, use Subscribed, not subscribed or Yes.
Tags are separated by semicolons, not commas.
pointsBalance is a positive number.
Birthdays use the YYYY-MM-DD format. Excel and other spreadsheet apps can change dates to a local format when you save the file.
Mobile numbers start with a plus sign. Spreadsheet apps can remove it.
You saved the file as a CSV file, not as a spreadsheet file.