Customers
Customer CSV format, validation, login accounts, and how customers link to pricing and account data.
Overview
The customer importer is a full snapshot of the storefront login accounts for one store. Each row creates or updates a customer, keyed by USERNAME.
The background job processes uploaded customer files about every 5 minutes.
File format
- Header row required. Headers are case-insensitive.
- Unknown columns are ignored. Duplicate headers are rejected.
- Files must be UTF-8. A leading UTF-8 BOM is allowed.
Columns
| Column | Required | Rules |
|---|---|---|
USERNAME | Yes | The customer's login name and the key for updates. Must not contain a comma. Maximum 255 characters. If the same username appears more than once, the last row wins. |
EMAIL | Yes | The customer's email address. Used for order confirmations and invite emails. |
PASSWORD | No | The customer's login password. See password rules below. |
PHONE | No | Contact phone number. Included in order notifications. |
CUSTOMER_ID | No | The ERP account code that links this customer to the accounts and customer pricing feeds. Values must match those feeds exactly. |
FIRST_NAME | No | Shown on the storefront account page and in order details. |
LAST_NAME | No | Shown with FIRST_NAME. |
CHECKOUT_NOTICE | No | Per-customer notice shown on the checkout page, e.g. delivery days or cut-off times. |
DELIVERY_TIMES | No | Per-customer delivery slots that override the store's delivery slots. Maximum 500 characters. Uses the same opening-hours format as the store's delivery slot settings. Requires the per-customer fulfilment slots feature. |
COLLECTION_TIMES | No | Same as DELIVERY_TIMES, for collection slots. |
SEND_INVITE_EMAIL | No | 1, true, or yes requests an invite email for a new customer created without a PASSWORD. Ignored for existing customers. Defaults to no. |
SEGMENTS | No | Accepted for legacy compatibility and ignored. |
ADDRESSES | No | Pipe-separated list of full delivery addresses. Shown in the checkout address picker in the order given. Addresses contain commas, so quote the whole cell. |
PAYMENT_REFERENCE | No | Up to 18 letters and digits, no spaces or punctuation. |
Boolean columns accept 1, true, or yes, and 0, false, or no. A blank cell means no. Any other value fails validation.
Passwords
- A value in
PASSWORDalways sets the customer's password, overwriting any existing one. - Blank for a new customer: a random 8-character password is generated. Combine this with
SEND_INVITE_EMAILso the customer receives their credentials. - Blank for an existing customer: their current password is kept.
Customer CSV files contain login credentials. Treat them as sensitive: leave PASSWORD blank for
existing customers unless you intend to reset it, and don't share or retain uploaded files
unnecessarily.
Linking to pricing and accounts
CUSTOMER_ID is the join key for the customer pricing and accounts feeds. Prices and account balances only appear for a customer when the CUSTOMER_ID values match exactly across the files. A customer without a CUSTOMER_ID can still log in and order, but sees no customer-specific prices, invoices, or account balance.
Validation
Customer imports are all-or-nothing. If one row fails validation, the whole file is rejected and nothing is imported.
When validation fails, the Import log shows a failure report with the rejected rows and reasons.
How updates are applied
Rows in the file are upserted as active customers. Every listed field is rewritten on each import, so include every column you use, populated, in every file - a blank optional cell clears the stored value.
Imported customers missing from the file are deactivated and can no longer log in. They are reactivated, with the values from the file, when their username reappears in a later import.
Customers who registered themselves on the storefront are never deactivated by imports. However, if a CSV row uses the same username as a self-registered customer, the import updates that account, including its password.
Example
USERNAME,EMAIL,PASSWORD,PHONE,CUSTOMER_ID,FIRST_NAME,LAST_NAME,CHECKOUT_NOTICE,SEND_INVITE_EMAIL,ADDRESSES,PAYMENT_REFERENCE
acme-001,buyer@example.com,,447700900123,ACME001,Jane,Buyer,Deliveries Tuesday and Friday. Order by 5pm the day before.,yes,"12 High Street, Basingstoke RG21 4AB|Unit 5 Mill Lane Estate, Basingstoke RG24 8PH",ACME001
acme-002,accounts@example.com,Str0ngPass24,447700900456,ACME002,Sam,Accounts,,no,"3 Market Square, Winchester SO23 8LB",ACME002Download the sample customer CSV to use as a template.