Skip to main content
The Location CSV Import feature allows you to bulk import warehouse locations, including their addresses and hierarchical relationships. This is essential when setting up your warehouse structure or migrating from another system.

​
What Can You Import?

A single CSV file can include:
  • Location Information: Name, type, ERP ID
  • Address Details: Complete address information for each location
  • Hierarchy: Parent-child relationships between locations
  • Status: Active or inactive locations
The import automatically creates parent locations if they don’t exist, making it easy to import complex warehouse hierarchies in a single file.

​
Import Workflow

The location import follows a 6-step wizard process:

​
Step 1: File Upload

  1. Navigate to Locations → CSV Import
  2. Click Choose File or drag-and-drop your CSV file
  3. Download the template if you need an example format
  4. System parses the CSV data

​
Step 2: Data Preview

  • Review the parsed location data in table format
  • Verify all locations were read correctly
  • Check for any obvious formatting issues
  • Click Next to proceed to validation

​
Step 3: Format Validation

The system validates CSV structure: Checks performed:
  • Required columns are present
  • Location types are valid
  • Address fields follow all-or-nothing rule
  • Country values are valid (US or Canada only)
Results:
  • ✅ Pass: Format is valid, proceed to business rules validation
  • ⚠️ Issues Found: Review and fix issues before proceeding

​
Step 4: Business Rules Validation

The system validates your data against business rules: Validation checks:
  • Parent locations are resolved (by name)
  • Duplicate locations detected (same name)
  • Address completeness verified
  • Auto-creation of missing parent locations planned
Results:
  • Shows which parent locations will be auto-created
  • Lists any duplicate locations that will be updated
  • Displays validation warnings and errors

​
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 locations were created/updated
  • 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 locations succeed, those 90 are created. Fix and retry the 10 that failed.

​
CSV File Format

Location CSV uses Title Case with Spaces for column headers (e.g., “Location Name”, not “LocationName”).

​
Required Columns

Your CSV must include these columns:
  • Location Name - Location name (required, must be unique)
  • Location Type - Type of location (required, see valid types below)
  • To Name - Name on address (required if any address field provided)
  • Address Line 1 - Street address line 1 (required if any address field provided)
  • City - City (required if any address field provided)
  • State/Province - State or province (required if any address field provided)
  • Zip Code - ZIP or postal code (required if any address field provided)
  • Country - Country (required if any address field provided)

​
Optional Columns

  • ERP ID - ERP system ID for the location
  • Address Line 2 - Street address line 2
  • Parent Location - Name of parent location (creates hierarchy)
  • Status - “Active” or “Inactive” (defaults to “Active”)

​
Valid Location Types

The Location Type column must contain one of these values:
  • Site - A physical site or facility
  • Warehouse - A warehouse facility
  • Customer - Customer location (special constraints apply - see below)
  • House - Greenhouse or growing house
  • Bin - Storage bin
  • Section - Warehouse section
  • Bay - Storage bay
  • Aisle - Warehouse aisle
  • Ship To - Shipping destination
  • Unknown - Unknown type
Invalid location types will cause validation errors and block the import. All location types must exactly match one of the values above. The system does not auto-correct invalid types.

​
CSV Structure Examples

​
Simple Location Import

Location Name,Location Type,To Name,Address Line 1,City,State/Province,Zip Code,Country
Main Warehouse,Warehouse,Acme Warehouse,123 Industrial Blvd,Portland,OR,97201,United States
North Greenhouse,House,North Facility,456 Garden Way,Seattle,WA,98101,United States

​
Location with Hierarchy

Location Name,Location Type,Parent Location,To Name,Address Line 1,City,State/Province,Zip Code,Country
Main Warehouse,Warehouse,,Acme Warehouse,123 Industrial Blvd,Portland,OR,97201,United States
Section A,Section,Main Warehouse,Acme Warehouse,123 Industrial Blvd,Portland,OR,97201,United States
Aisle 1,Aisle,Section A,Acme Warehouse,123 Industrial Blvd,Portland,OR,97201,United States

​
Complete Location Record

Location Name,Location Type,ERP ID,Parent Location,To Name,Address Line 1,Address Line 2,City,State/Province,Zip Code,Country,Status
Main Warehouse,Warehouse,WH-001,,Acme Warehouse,123 Industrial Blvd,Building 1,Portland,OR,97201,United States,Active
North House,House,GH-001,Main Warehouse,Acme Warehouse,123 Industrial Blvd,Building 2,Portland,OR,97201,United States,Active
Old Storage,Bin,BIN-999,Main Warehouse,Acme Warehouse,123 Industrial Blvd,,Portland,OR,97201,United States,Inactive

​
Business Rules

​
Customer Location Requirements

Critical: A Customer location is required for the location import system to function. Customer Location Rules:
  1. Must Exist: A Customer location must exist in your system before importing other locations
  2. Maximum One: Your CSV can contain at most one Customer location
  3. No Parent Allowed: Customer locations cannot have a parent location - they are the root of your location hierarchy
  4. Acts as Root: All other location types must have a path leading back to the Customer location
If you include a Customer location in your CSV:
  • It will be imported first (before all other locations)
  • It must not have a Parent Location value
  • Multiple Customer locations in one CSV will cause validation errors
If you don’t include a Customer location in your CSV:
  • The system will use the existing Customer location in your system
  • All other locations will be organized under this existing Customer location
  • Import will fail if no Customer location exists in the system
Import Requirement: The import will fail if no Customer location exists in your system and none is provided in the CSV. Ensure a Customer location exists before importing other location types.

​
Site Location Behavior

Site locations have special automatic parent assignment: Automatic Parent Assignment:
  • If a Site location has no Parent Location specified, the system automatically assigns the Customer location as its parent
  • This ensures Site locations are properly anchored in the hierarchy
  • You can override this by explicitly specifying a different parent (such as another Site)
Site Requirements for Other Location Types:
  • All non-Site, non-Customer location types (Warehouse, House, Bin, Section, Bay, Aisle, Ship To) must have a path to a Site location through their parent chain
  • The system validates that the parent hierarchy eventually leads to a Site location
  • If no Site is found in the parent chain, the location will fail to import
Example Hierarchy: 
Customer (root)
└── Site A
    └── Warehouse 1
        └── Section A
            └── Aisle 1
                └── Bin 10
In this example:
  • Site A automatically has Customer as parent (if not specified)
  • Bin 10’s parent chain is: Bin 10 → Aisle 1 → Section A → Warehouse 1 → Site A
  • The system validates that Site A exists in the chain
The system internally tracks a siteParentId field for all non-Site/non-Customer locations. This field references the ultimate Site location in the parent chain and is automatically calculated during import.

​
Address Validation (All-or-Nothing)

Important: If you provide ANY address field, you must provide ALL required address fields. Required address fields (when any address field is present):
  • To Name
  • Address Line 1
  • City
  • State/Province
  • Zip Code
  • Country
Optional:
  • Address Line 2
If you omit all address fields, the location will be created without an address.

​
Country Validation

The system only supports two countries:
  • United States (default if empty)
  • Canada
Any other country value will cause an error and block that row from importing.

​
Parent Location Auto-Creation

When you specify a Parent Location:
  1. System searches for existing location by name
  2. If not found, automatically creates the parent location with:
    • Name from CSV
    • Location Type: “Site” (all auto-created parents become Site type)
    • Parent Location: Automatically assigned to the Customer location
    • No ERP ID
    • No address
  3. Then creates your location as a child of that parent
This means you can import child locations before their parents exist - the system will create the parents automatically as Site type locations!
Auto-created parent locations are always created as Site type and placed under the Customer location in the hierarchy. If you need a different type, create the parent location explicitly in your CSV before the child locations.

​
Create vs Update Behavior

The import can create new locations or update existing ones: Finding existing locations:
  • System searches by Location Name (exact match)
If location exists (duplicate):
  • Only the status can be updated if provided in CSV
  • The location is counted as “updated” (verified in system)
  • Other fields (address, type, parent) are NOT updated
  • Use the UI to manually update other fields if needed
If location doesn’t exist:
  • Creates new location with all provided data
  • New locations are ALWAYS created with Status: Active
  • Status from CSV is ignored for new locations (see Status Handling below)
  • Address is saved if all required address fields are provided

​
Status Handling

The Status column behavior differs for new vs existing locations: For NEW locations (not yet in system):
  • All new locations are created with Status: Active
  • Status column is ignored for new locations
  • You will see a warning if you specify “Inactive” for a new location
  • To inactivate a new location, update it after import via the UI
For EXISTING locations (duplicates):
  • Empty or “Active”: Updates location to Active (if currently Inactive)
  • “Inactive”: Updates location to Inactive (if currently Active)
  • Any other value: Treated as Active
  • No status change if current status matches CSV value
Status updates are applied using separate mutations after the location is created or found. This is why new locations must be created as Active first, then updated separately if needed.

​
Best Practices

​
Preparing Your CSV

CSV Preparation Tips

  • Use UTF-8 encoding to support special characters
  • Keep location names consistent and unique
  • Use Title Case with Spaces for column headers
  • Test with a small file first (5-10 locations)
  • Validate your CSV in a spreadsheet before uploading
  • Remove empty rows and columns
  • Ensure address fields are complete (all-or-nothing rule)

​
Building Location Hierarchies

Flat import approach: 
Location Name,Location Type,Parent Location
Main Warehouse,Warehouse,
Section A,Section,Main Warehouse
Section B,Section,Main Warehouse
Aisle 1,Aisle,Section A
Aisle 2,Aisle,Section A
The system will:
  1. Create Main Warehouse
  2. Create Section A and B under Main Warehouse
  3. Create Aisles under Section A
Top-down approach (recommended): Import parents first, then children in separate files or rows. This gives you more control over parent location details.

​
Data Quality

Before importing:
  • Verify location names are unique and descriptive
  • Ensure addresses are complete and accurate
  • Check that location types match your warehouse structure
  • Confirm parent location names match exactly
  • Validate country is “United States” or “Canada”

​
Large Imports

For importing hundreds or thousands of locations:
  • Break into smaller batches (100-200 locations per file)
  • Import top-level locations first
  • Then import child locations
  • Test with one batch before importing all
  • 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 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:
  • Check that all required column headers are present
  • Verify exact spelling: “Location Name”, “Location Type”, etc.
  • Use Title Case with Spaces (not PascalCase or snake_case)
Invalid location type:
  • Review valid location types list above
  • Invalid types cause validation errors and block the import
  • Ensure location type exactly matches one of the valid values
Address validation fails:
  • Remember: all-or-nothing rule for addresses
  • If you include ANY address field, include ALL required fields
  • Check for empty cells in required address columns
Invalid country:
  • Only “United States” or “Canada” are supported
  • Leave empty to default to “United States”
  • Any other value will cause an error

​
Data Validation Issues

Common data errors: Parent location not found:
  • System will auto-create parent locations
  • Ensure parent location names match exactly
  • Check for typos or extra spaces
Duplicate location names:
  • System will update existing locations with same name
  • Verify this is the intended behavior
  • Consider using different names if you want separate locations
Status not updating:
  • Verify Status column contains “Active” or “Inactive”
  • Status is set after location creation
  • Check import results for status update errors

​
Import Failures

If individual locations fail during import:
  1. Review the error message for that location
  2. Common causes:
    • Required field missing despite format validation passing
    • Invalid data constraint
    • Parent location creation failed
  3. Fix the issue in your CSV
  4. Use the Retry button to import only failed records

​
Partial Success

If some locations import but others fail:
  • Successful imports are NOT rolled back
  • Failed locations can be retried after fixing
  • Or manually create the failed locations
  • Check if parent location auto-creation caused issues
The import handles each location independently. One failed location won’t prevent others from succeeding.

​
After Import

​
Verify Imported Data

After successful import:
  1. Navigate to Locations list
  2. Search for imported locations by name
  3. Open location details to verify:
    • Location type is correct
    • Address is accurate
    • Parent-child relationships are correct
    • Status is set properly

​
Fix Issues

If you find issues after import:
  • Edit locations directly in the UI
  • Update addresses or location types
  • Adjust parent-child relationships
  • Change status (activate/inactivate)
  • No need to delete and re-import

​
Next Steps

After importing locations:
  • Organize your location hierarchy
  • Assign inventory to locations
  • Set up location-specific settings
  • Train staff on warehouse organization

​
Next Steps