Skip to main content

Import customers from a spreadsheet

The spreadsheet importer is the fastest way to load a customer book — from another system, a marketplace export, or a bulk edit of your own export. It runs in four steps inside one dialog: upload, map columns, validate, import. Nothing is written until the final step.

To add a single customer, use Add Customer on the list instead — see Create & edit a customer.

Before you begin​

  • The Import button is permission-gated — if you can't see it, ask your admin.
  • A Default Sales Rep column is created on the fly if the named rep doesn't exist yet; a Sales Channel Origin must already exist to match.
  • Know your update key — see How rows match existing customers.

Steps​

  1. On the customers list, click Import (top right). The Import Customers dialog opens on Upload.
  2. Provide your data: drag and drop a CSV, TSV, or Excel file, click Choose File, or paste CSV/TSV text. The Column separator (auto / comma / tab / semicolon) can be overridden when pasting.
  3. Click Next: Map Columns. Map each of your columns to a customer field or leave it as skipped — only Name is required. See the importable columns reference.
  4. Click Next: Validate and review the preview and any per-row errors.
  5. Click Import. The rows process as a background job — track it in the job tray.

How rows match existing customers​

The importer decides update-vs-create per row, in this order:

  1. ID — if an id column is mapped and filled, that exact customer is updated. An ID that doesn't exist fails the row with an error.
  2. Email — otherwise, a filled email matches the existing customer with that email. An email no customer has means a new customer is created (the name alone won't be used to match).
  3. Name + Zip + Address Line 1 — otherwise, this trio matches an existing customer by address.
  4. Name only — as a last resort, a bare name matches a customer with that name that has no email or address on file.
  5. Anything else creates a new customer, with the row's address saved as both the default shipping and billing address.

Next steps​

Video transcript

Bringing customers in from another system? Import them in bulk. On the customers list, click Import. Upload a file, or paste rows straight in. Map each column — only Name is required. Validate to catch problems before anything is written, then import. The rows process in the background. Existing customers match by ID or email, so re-importing an edited export updates records instead of duplicating them.

Last verified: