Skip to main content
The Customer CSV Import feature allows you to bulk import customers along with their locations, contacts, and billing addresses in a single file. This is much faster than creating customers individually when you have many to add.

​
What Can You Import?

A single CSV file can include:
  • Customer Information: Name, description, and payment terms
  • Customer Locations: Multiple delivery locations per customer with addresses, codes, and optional details
  • Contacts: Multiple contacts per customer with names, emails, and phone numbers
  • Billing Addresses: Multiple billing addresses per customer
The CSV import supports complex customer structures. One customer can have multiple locations, each location can have multiple contacts, and each customer can have multiple billing addresses.

​
Import Workflow

The customer import follows a 6-step wizard process:

​
Step 1: File Upload

  1. Navigate to Customers → CSV Import
  2. Click Choose File or drag-and-drop your CSV file
  3. The system parses the CSV and moves to preview

​
Step 2: Data Preview

  • Review the parsed CSV data in a table
  • Verify data was read correctly
  • Check for obvious formatting issues
  • Click Next to proceed

​
Step 3: Format Validation

The system validates your CSV format: Checks performed:
  • Required columns present (customer name, etc.)
  • Valid data types (emails formatted correctly, etc.)
  • No critical structural issues
Results:
  • ✅ Pass: Format is valid, proceed to data validation
  • ⚠️ Issues Found: Review and fix issues before proceeding
Format validation checks the structure of your file. Data validation (next step) checks if customers, terms, etc. already exist in the system.

​
Step 4: Data Validation

The system validates your data against existing records: Validation checks:
  • Duplicate customers (same name or ERP ID)
  • Duplicate locations for a customer (same location code)
  • Duplicate contacts (same name/email for a customer)
  • Duplicate billing addresses
  • Payment terms existence (creates if missing)
Grouping:
  • Customers are grouped by name
  • Locations, contacts, and addresses are nested under each customer
  • You’ll see how many of each entity will be created

​
Step 5: Import Progress

  • Click Start Import to begin
  • Progress bar shows import status
  • Real-time feedback on successes and failures
  • Can take several minutes for large imports

​
Step 6: Results

Review the import results:
  • Success count: How many entities were created
  • Failure count: How many had errors
  • Error details: Specific reasons for failures
  • Retry option: Fix issues and retry failed records
Failed imports don’t roll back successful ones. If 90 out of 100 customers succeed, those 90 are created. Fix and retry the 10 that failed.

​
CSV File Format

​
Required Columns

Your CSV must include these columns for customers:
  • CustomerName - Customer name (required, used for grouping)
  • CustomerDescription - Description or notes (optional)
  • CustomerTerms - Payment terms name (optional, auto-created if doesn’t exist)

​
Location Columns

To add locations for customers:
  • LocationCode - Unique code for the location (required if adding locations)
  • LocationName - Location name (required if adding locations)
  • LocationAddressLine1 - Street address line 1
  • LocationAddressLine2 - Street address line 2 (optional)
  • LocationCity - City
  • LocationState/Province - State or province
  • LocationZipcode - ZIP or postal code
  • LocationAddressToName - Name on location address (optional)
  • LocationDescription - Location description (optional)
  • LocationTerms - Location-specific payment terms (optional)
  • StoreNumber - Store number (optional)
  • GLN - Global Location Number (optional)

​
Contact Columns

To add contacts:
  • ContactFirstName - Contact’s first name
  • ContactLastName - Contact’s last name
  • ContactEmailAddress - Contact’s email address
  • ContactPhoneNumber - Contact’s phone number
  • ContactTitle - Job title (optional)

​
Billing Address Columns

To add billing addresses:
  • BillingToName - Name on billing address (optional)
  • BillingAddressLine1 - Street address line 1
  • BillingAddressLine2 - Street address line 2 (optional)
  • BillingCity - City
  • BillingState/Province - State or province
  • BillingZipcode - ZIP or postal code

​
CSV Structure Examples

​
Simple Customer Import

CustomerName,CustomerDescription
Acme Gardens,Retail nursery chain
Green Thumb Co,Wholesale distributor

​
Customer with Location

CustomerName,LocationCode,LocationName,LocationAddressLine1,LocationCity,LocationState/Province,LocationZipcode
Acme Gardens,ACME-01,Main Store,123 Garden Way,Portland,OR,97201

​
Complete Customer Record

CustomerName,CustomerTerms,LocationCode,LocationName,ContactFirstName,ContactLastName,ContactEmailAddress,ContactPhoneNumber,BillingToName,BillingAddressLine1,BillingCity,BillingState/Province,BillingZipcode
Acme Gardens,Net 30,ACME-01,Main Store,John,Doe,[email protected],503-555-0100,Acme Gardens Inc,123 Garden Way,Portland,OR,97201

​
Multiple Records for Same Customer

CustomerName,LocationCode,LocationName
Acme Gardens,ACME-01,Main Store
Acme Gardens,ACME-02,North Branch
Acme Gardens,ACME-03,South Branch
Repeat the customer name on multiple rows to add multiple locations, contacts, or billing addresses for the same customer.

​
Data Grouping

​
How Customers are Grouped

The import groups rows by CustomerName:
  • All rows with “Acme Gardens” are combined into one customer
  • Each unique location code becomes a separate location
  • Each unique contact (by name/email) becomes a separate contact
  • Each unique billing address becomes a separate address

​
Duplicate Detection

The system detects duplicates: Customer Duplicates:
  • Same customer name already exists
  • Same ERP ID already exists
  • Action: Skips creating duplicate customer
Location Duplicates:
  • Same location code for this customer
  • Action: Skips duplicate location
Contact Duplicates:
  • Same name and email for this customer
  • Action: Skips duplicate contact
Billing Address Duplicates:
  • Same address details for this customer
  • Action: Skips duplicate address

​
Payment Terms

​
Auto-Creation of Terms

If you specify a terms name that doesn’t exist:
  • The system automatically creates the terms
  • Terms are created as “Active”
  • Terms name is stored for the customer/location

​
Terms Assignment

Terms can be specified at two levels:
  1. Customer Level: CustomerTerms column applies to customer
  2. Location Level: LocationTerms applies to specific location
Location terms override customer terms for that location.

​
Best Practices

​
Preparing Your CSV

CSV Preparation Tips

  • Use UTF-8 encoding to support special characters
  • Keep customer names consistent (exact spelling)
  • Use unique location codes across all customers
  • Test with a small file first (5-10 customers)
  • Validate your CSV in a spreadsheet before uploading
  • Remove empty rows and columns
  • Ensure all required fields have values

​
Data Quality

Before importing:
  • Verify customer names don’t have typos
  • Ensure email addresses are valid
  • Check phone number formatting is consistent
  • Validate addresses are complete with all required fields
  • Verify location codes are unique within each customer
  • Confirm payment terms names are correct (will be auto-created if missing)

​
Large Imports

For importing hundreds or thousands of customers:
  • Break into smaller batches (100-200 customers per file)
  • Import critical customers first
  • Test with one batch before importing all
  • Schedule imports during off-peak hours
  • Monitor results carefully for each batch

​
Troubleshooting

​
File Upload Fails

If upload doesn’t work:
  • Check file size (very large files may timeout)
  • Verify file is actually CSV format (not Excel .xlsx)
  • Ensure file encoding is UTF-8
  • Try a smaller file to isolate the issue
  • Check your internet connection

​
Format Validation Errors

Common format errors:
  • Missing required columns (CustomerName)
  • Invalid email format (missing @ or domain)
  • Invalid data types (text in numeric fields)
  • Extra commas or quotes causing parsing issues
Fix: Review the error messages, correct your CSV, and re-upload.

​
Data Validation Issues

Common data errors:
  • Duplicate customer names (different spelling variations)
  • Location codes not unique within customer
  • Invalid terms names (if not auto-creating)
  • Malformed addresses
Fix: Review the validation results, update your CSV based on feedback, and retry.

​
Import Failures

If individual customers fail during import:
  1. Review the error message for that customer
  2. Common causes:
    • Required field missing
    • Invalid foreign key reference
    • Data constraint violation
  3. Fix the issue in your CSV
  4. Use the Retry button to import only failed records

​
Partial Success

If some customers import but others fail:
  • Successful imports are NOT rolled back
  • Failed customers can be retried after fixing
  • Or manually create the failed customers
  • Check if duplicates caused some to skip
The import is atomic per customer group. Either all entities for a customer succeed, or all fail. This prevents partial customer records.

​
After Import

​
Verify Imported Data

After successful import:
  1. Navigate to Customers list
  2. Search for imported customers by name
  3. Open customer details to verify:
    • Locations were created correctly
    • Contacts are assigned properly
    • Billing addresses are accurate
    • Pricing and terms are correct

​
Fix Issues

If you find issues after import:
  • Edit customers directly in the UI
  • Add missing locations or contacts
  • Correct any data errors
  • No need to delete and re-import

​
Next Steps

After importing customers:
  • Assign price groups if not imported
  • Review customer settings and permissions
  • Train staff on new customer accounts
  • Create initial orders for new customers

​
Next Steps