# Importing customers

> Bring customers from Square, Shopify, Mailchimp or a spreadsheet into Leal with a CSV file, and understand how Leal matches and updates them.

You can bring your existing customers into Leal in one go by uploading a CSV file. Leal matches each row to a customer you already have where it can, updates them, and creates new customers for everyone else. The one thing to know before you start: **an import brings across people, not stamps or cards.**

## Before you start

You need a CSV file (a spreadsheet saved as "CSV"). Most systems can export one: Square, Shopify, Mailchimp, your POS, or a spreadsheet you've kept yourself.

Click **Import** on the **Customers** page, then **Download sample CSV** to get a file with the right column headings already in place. Copy your customers into it, or rename the headings in your own file to match.

## The columns

The first row of the file must be the column headings. Headings can be in any order, and capitals or extra spaces around them don't matter. Any column Leal doesn't recognise is ignored.

| Column | Required? | What to put in it |
| ------ | --------- | ----------------- |
| `first_name` | Yes | The customer's first name. |
| `last_name` | No | Their last name. |
| `email` | If `phone` is empty | Their email address. Must be unique within your store. |
| `phone` | If `email` is empty | Their phone number. Use full international format, such as +447911123456. |
| `birthday` | No | Their date of birth as `YYYY-MM-DD`, such as 1990-04-15. |
| `source` | No | The system the customer comes from, such as `square` or `shopify`. Use it together with `external_id`. |
| `external_id` | No | The customer's ID in that system, such as their Square customer ID. |

Every row needs a first name and at least one of email or phone.

### Why bother with source and external ID?

If you fill in `source` and `external_id`, Leal remembers which customer in the other system each Leal customer is. Later imports, Zaps and API calls can then find the right customer by that ID, even if their email or phone changes. It's worth filling in if you're coming from a system you'll keep using alongside Leal.

## How matching works

For each row, Leal looks for an existing customer in this order:

1. If the row has both `source` and `external_id`, a customer already linked to that ID.
2. Otherwise, or if nobody is linked yet, a customer with the same email address.
3. Then a customer with the same phone number.
4. If nobody matches, Leal creates a new customer.

When a row matches an existing customer, Leal updates them with the values in the row. **Empty cells never wipe out what you already have**, so a row with no birthday won't remove a birthday you've saved.

That makes importing safe to repeat. If you run the same file twice, the second run updates the same customers instead of creating duplicates.

## Run the import

1. On the **Customers** page, click **Import**.
2. Under **CSV file**, choose your file. It must be a CSV of 10MB or less. UTF-8 is recommended.
3. Click **Start import**.

You'll see "Import started. We'll email you a report when it finishes." The import runs in the background, so you can carry on working.

## The import report

When it finishes, the person who uploaded the file gets an email with the totals and a link to the full **Customer import report** in Leal. The report shows:

- **Total rows**: rows read from the file, not counting the heading row.
- **Created**: new customers added.
- **Updated**: existing customers that matched and were updated.
- **Failed**: rows that couldn't be imported.
- An error table with the **Row** number and **Error** for up to the first 200 failed rows. Row 2 is the first row under the headings, which matches the row numbers in a spreadsheet.

Fix the failed rows in your file and import it again. Rows that worked the first time will just be matched and updated.

## What an import doesn't do

- **No stamps.** Stamp counts in your file aren't read. Add stamps afterwards with [manual adjustments](https://docs.getleal.com/customers/adjusting-stamps).
- **No cards.** Imported customers don't get a loyalty card automatically. They get one when they sign up through your poster or when you assign one on their profile.
- **No messages.** Nobody is emailed or texted as part of an import.

> [!WARNING]
> Imported customers count as subscribed to your campaigns, just like customers who signed up themselves. Only import people who have agreed to hear from your store, and check the rules on marketing consent where you trade.

## Gotchas

- **Phone numbers without a country code are read as UK numbers.** A local number such as 0871234567 from outside the UK might fail or be saved wrongly. Put the country code on every number (+353 for Ireland, +1 for the US and Canada, and so on).
- **Birthdays in other formats can be dropped.** If Leal can't read a birthday, the customer is still imported but without a birthday. It isn't reported as an error. Stick to `YYYY-MM-DD`. Dates like 04/05/1990 are ambiguous and might be read as the wrong day and month.
- **Duplicates inside your own file.** Two rows with the same email address will be treated as the same customer. The second row updates the first.
- **Excel and special characters.** If names with accents come out garbled, save the file as "CSV UTF-8" and import again.
- **Connected Square or Shopify.** If your store is set up to send new Leal customers to Square or Shopify, customers created by an import are sent too. See [Point of sale integrations](https://docs.getleal.com/integrations/point-of-sale).

## Best practices

- Import a small test file of five or ten customers first and check them on the **Customers** page.
- Use the export as a template. An [export](https://docs.getleal.com/customers/exporting-customers) uses exactly the same columns, so you can export, edit in a spreadsheet and import back.
- Tidy your list before importing: remove test entries and people who have asked not to be contacted.
