Skip to content

Importing Customers

The Customer Import/Update Tool lets you upload an Excel spreadsheet to create new customer records in bulk, update existing ones, or both in a single pass. It walks you through four steps — Upload File, Map Columns, Preview Changes, and Import Results — and nothing is written to your customer database until you've reviewed a preview and clicked Start Import.

Typical uses: loading a customer list from a previous POS system, appending email addresses collected at an event, or bulk-updating mailing preferences or customer classes.

Availability

The Customer Import/Update Tool is enabled per-client by VMX. When enabled, it appears as the Import/Export tab on the Customers page. If you don't see that tab and would like to use it, contact help@vmxllc.com to discuss enabling it for your store.

Preparing your spreadsheet

The Customer Import/Update Tool accepts Excel .xlsx files only — if your data is in a CSV or an older .xls file, open it in Excel (or Google Sheets / Numbers) and save it as .xlsx first. If you upload anything else you'll get the error "Only XLSX files are supported."

Guidelines for the file:

  1. The workbook should contain only one worksheet. Delete any extra sheets before uploading — the tool reads its column headers from the first sheet, but rows on other sheets can still be pulled into the import and cause unexpected results.
  2. Use one row per customer, with a header row on top (e.g. First Name, Last Name, Email). The tool reads the header row and can auto-match common column names for you.
  3. To create new customers, every row needs at least a first name and a last name.
  4. To update existing customers, include an identifier column the tool can match on: customer number, email address, or phone number. Customer number is the most reliable.
  5. If you're both creating and updating in one file, include first name, last name, and your identifier column.
  6. Column order doesn't matter, and you don't need a column for every field — you'll map your columns to VMX fields in Step 2, and unmapped columns are simply ignored.

The maximum upload size is shown on the upload screen. If your file is larger, split it into multiple smaller files.

Excel gotchas: leading zeros, ZIP codes, and mangled numbers

Excel silently reformats data in ways that can corrupt a customer import, usually when a CSV export from another system is opened in Excel and re-saved. Check for these before uploading to the Customer Import/Update Tool:

  • Leading zeros stripped. Excel treats ZIP codes, phone numbers, and customer numbers as numbers, so 01234 becomes 1234. A Northeast-US ZIP like 06770 importing as 6770 is the classic symptom. Fix: format those columns as Text in Excel before pasting or opening the data, or re-add the zeros before uploading.
  • Long numbers turned into scientific notation. A long account or phone number can display and save as something like 5.55124E+9, which will not match any existing customer. Format the column as Text to prevent it.
  • Dates auto-converted. Excel silently converts anything that looks like a date into its own internal date cell type, which the import may not read correctly. Format date columns (birthdays, tax expirations) as Text in Excel so the cell holds the literal characters 2025-03-15 (recommended) or 03/15/2025, and spot-check the column after any open/save round-trip. Avoid written-out dates like "March 15, 2025".
  • Currency symbols added. Credit limit and reward dollar columns must contain plain numbers (1000.00), not $1,000.00. Re-format the column as a plain number with no symbol or thousands separator.

A quick spot-check of the sample rows shown in Step 2 (and the Step 3 preview) will catch most of these before anything is imported.

Step 1: Upload File

  1. Open the Customers page and click the Import/Export tab. The Customer Import/Update Tool opens on the Upload File step.
  2. Drag your .xlsx file onto the box labeled Drop file here or click to select, or click it to browse for the file. The upload starts as soon as a file is chosen (the Upload File button also starts it).
  3. A progress bar shows the upload; when it finishes you're taken to the Map Columns step.

Step 2: Map Columns

The Map Columns step shows your file's column headers with a few rows of sample data underneath, and a list of Available Fields (First Name, Last Name, Email, Phone, ZIP/Postal Code, and so on).

  1. The tool auto-maps columns whose headers use common names ("First Name", "Email", "Zip Code", "Mobile", etc.). Review what it matched.
  2. To map a column manually, drag a field from Available Fields onto the column's header — or click the field, then click the column header when the prompt "Now click on a column header to assign this field" appears.
  3. Leave any columns you don't want imported unmapped; they are ignored.
  4. Set the Import Options (described below) and choose the Identify existing customers by: field.
  5. Click Validate & Preview. You must map at least one column, or you'll see "Please map at least one column before continuing."

Import options: create, update, or both

Three checkboxes on the Map Columns step control what the Customer Import/Update Tool does with each row:

  • First row contains headers — checked by default. Uncheck it only if your file starts directly with data (the first row will then be imported as a customer).
  • Create new customers if not found — rows that don't match an existing customer become new customer records. Requires First Name and Last Name to be mapped; otherwise you'll see "First Name and Last Name are required for creating new customers."
  • Update existing customers — rows that match an existing customer update that customer's record. Requires the identifier field to be mapped; otherwise you'll see "The identifier field (number) must be mapped for updating existing customers" (or email / phone, depending on your chosen identifier).

At least one of the two actions must be enabled. With both enabled, each row is first matched against existing customers; matches are updated and non-matches are created. With only Update existing customers enabled, unmatched rows are flagged as errors and skipped — useful when you want to be certain the import can't create duplicates.

How existing customers are matched

When Update existing customers is enabled, the Identify existing customers by: dropdown on the Map Columns step controls how each row is matched to a customer already in VMX:

  • Customer Number — recommended. Matches the VMX customer number exactly; customer numbers are unique and never change. Use this whenever your spreadsheet came from VMX in the first place.
  • Email Address — matches against both the customer's primary Email and Alt Email fields. Good when you have emails but not customer numbers. Customers with no email on file can't be matched this way.
  • Phone Number — matches on digits only, so (555) 123-4567, 555-123-4567, and 5551234567 all match the same customer. The number must include the area code (at least 10 digits) to match. Be aware that family members sometimes share a phone number, and a shared number can match a different household member than you intended.

If a row's identifier doesn't match anyone and Create new customers if not found is enabled, that row creates a brand-new customer — so inaccurate identifier data is the main way an import produces duplicates. When in doubt, run the import with only updates enabled first, review which rows come back unmatched, and handle those separately.

Step 3: Preview Changes

The Preview Changes step of the Customer Import/Update Tool shows what the import will do, for up to the first 100 rows of the file, before anything is written. New customers are shown in green, updated customers in blue. If your file has more than 100 rows, the preview (and its counts) covers only the first 100 — the remaining rows are processed with the same rules when you start the import.

Each row shows a Status — New, Update, No Change, or Error — along with the matched Customer #, the Name, and a Changes/Issues column. For updates, Changes/Issues lists each field change as old value → new value, so you can verify the import is changing what you expect. Rows whose values already match show "No changes detected". One caveat: a field that is currently blank on the customer's record may not appear in the change list, but the import still fills it in from your file.

  1. Use the filter buttons — All Records, New Customers, Updates, Errors — to review each group. The counts above the table show how many of each the preview found.
  2. Check the Errors filter first. Common issues are listed per-row (for example, a missing required name field, or a row that matched no customer while creating is disabled).
  3. If something looks wrong, click Back to adjust your column mapping or options — nothing has been imported yet.
  4. When you're satisfied, click Start Import and confirm the prompt "Are you sure you want to start the import? This will affect your customer data."

If VMX Email Marketing is enabled for your store, the Preview Changes step shows an extra checkbox: "This file's marketing flag reflects consent these people actually gave."

Tick it only when you know the source system recorded a real opt-in for the Wants Email values in your file — for example, you're migrating from an email platform where these people subscribed themselves. If you leave it unticked (the default), the import still sets the Wants Email flag on each customer, but VMX does not record it as proof of consent — and those customers are emailable only while they have a recent purchase. See the Email Marketing documentation for how consent affects who campaigns can be sent to.

Step 4: Import Results

After you click Start Import, the Customer Import/Update Tool processes the file in batches and shows live progress: a progress bar, a running count of records processed, and an Import Log listing each customer created or updated.

When it finishes, the Import Summary shows:

  • Total records processed
  • New customers created
  • Existing customers updated
  • Errors

From here you can click View Customers to jump to the Customer Search page, View Detailed Log to review the row-by-row log (including the reason for any errors), or Start Over to run another import.

Keep the browser tab open until the progress bar completes — the import runs from your browser session.

Customer fields you can import

The Customer Import/Update Tool can fill any of these fields, matching what you see on a customer's profile page:

  • Identity: Customer Number, First Name, Last Name, Gender, Title, Company, Birthday
  • Contact: Phone, Cell Phone, Fax, Email, Alt Email
  • Address: Address Line 1, Address Line 2, City, State, ZIP/Postal Code, Country
  • Financial: Taxable, Tax Number, Tax Expiration, Credit Limit, Credit Status
  • Marketing & preferences: Wants Postal Mail, Wants Email, Wants Texts, How Did They Hear
  • Loyalty: Loyalty Member, Reward Dollars
  • Other: Short Memo, Memo, Customer Class, Inactive, Master Customer Number (for linked accounts)

Data formats the import accepts

How to format values in your spreadsheet for the Customer Import/Update Tool:

  • Names — the first letter of the first and last name is capitalized automatically ("john" / "smith" imports as "John" / "Smith") and stray spaces are trimmed.
  • Emails — use a full address like user@example.com; addresses are converted to lowercase automatically. The tool does not verify that an address is real, so typos import as-is.
  • Dates (Birthday, Tax Expiration) — 2025-03-15 (recommended), 03/15/2025, or 3/15/2025, in a Text-formatted column (see the Excel gotchas section above). Avoid written-out dates like "March 15, 2025".
  • Yes/no fields (Taxable, Wants Postal Mail, Wants Email, Wants Texts, Loyalty Member, Inactive) — use 1 for yes and 0 for no. A blank cell leaves the field unchanged — it does not mean no.
  • Money/decimal fields (Credit Limit, Reward Dollars) — plain numbers like 1000.00 or 250. No currency symbols or thousands separators.
  • Phone numbers — any common format works for matching existing customers ((555) 123-4567, 555-123-4567, 5551234567). The number is stored exactly as it appears in your file, so pick one consistent format for the whole column.
  • Blank cells are skipped — a blank cell does not clear the existing value on an updated customer.

Common customer import errors and fixes

Errors you may see in the Customer Import/Update Tool, with causes and fixes:

  • "Only XLSX files are supported" — the uploaded file isn't a .xlsx workbook. Re-save your CSV or .xls file as .xlsx in Excel and upload again.
  • "First Name and Last Name are required for creating new customers." — Create new customers if not found is checked but firstName/lastName aren't mapped. Map both columns in Step 2, or uncheck the create option.
  • "The identifier field (number) must be mapped for updating existing customers." — Update existing customers is checked but the column for your chosen identifier (Customer Number, Email Address, or Phone Number) isn't mapped; the message names whichever identifier you chose. Map that column, pick a different identifier, or uncheck the update option.
  • "You must enable at least one action: create new customers or update existing ones" — both action checkboxes are unchecked. Enable at least one.
  • "Please map at least one column before continuing." — you clicked Validate & Preview with no columns mapped.
  • "Customer not found and creating new customers is disabled" — shown per-row when a row matches no existing customer and Create new customers if not found is off. Fix the identifier value in that row, or enable creating if the row really is a new customer.
  • Rows flagged with "Missing required field" — a row being created is missing its first or last name. Fill in the cell or remove the row.
  • File too large to upload — the file exceeds the maximum size shown on the upload screen. Split the import into multiple smaller files, or delete unused columns and formatting.