Skip to main content
The Category CSV Import feature allows you to bulk import item categories with their configuration. Categories help organize your item catalog and control unit of measure (UOM) conversions.

​
What Can You Import?

A single CSV file can include:
  • Category Code: Unique identifier for the category
  • Category Name: Display name
  • Eaches: Number of individual units in a case/package
  • UOM: Unit of measure multiplier
The import automatically updates existing categories if a matching code is found, making it easy to bulk update category configurations.

​
Import Workflow

The category import follows a 6-step wizard process:

​
Step 1: File Upload

  1. Navigate to Product → Categories → 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 category data in table format
  • Verify all categories 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:
  • All required columns are present
  • Category codes follow valid format
  • Category names don’t exceed maximum length
  • Eaches and UOM values are valid positive integers
  • No duplicate codes within the CSV file
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:
  • Existing categories detected (by code)
  • New categories identified
  • Create vs update actions determined
Results:
  • Shows which categories will be created (new codes)
  • Lists categories that will be updated (existing codes)
  • 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
  • Processes one category at a time

​
Step 6: Results

Review the import results:
  • Success count: How many categories were created/updated
  • Failure count: How many had errors
  • New categories: How many were created
  • Updated categories: How many were updated
  • Error details: Specific reasons for failures
Failed imports don’t roll back successful ones. If 8 out of 10 categories succeed, those 8 are created/updated. Fix and retry the 2 that failed.

​
CSV File Format

Category CSV uses PascalCase for column headers (e.g., “Code”, “Name”, not “code”, “name”).

​
Required Columns

All columns are required for category import:
  • Code - Unique category identifier (required, 1-32 characters)
  • Name - Category display name (required, max 64 characters)
  • Eaches - Number of eaches per unit (required, positive integer)
  • UOM - Unit of measure multiplier (required, positive integer)
Unlike other CSV imports, the category import has no optional fields. All four columns must be present and populated for every row.

​
Valid Values

Code Requirements:
  • 1-32 characters maximum
  • Must be unique within the CSV file
  • Examples: MEAT-BEEF, PRODUCE-VEG, DAIRY MILK
Name Requirements:
  • 1-64 characters maximum
  • Any characters allowed
  • Examples: Beef Products, Fresh Vegetables, Milk Products
Eaches Requirements:
  • Must be a positive integer (whole number)
  • Must be greater than 0
  • Represents individual units in a package
  • Examples: 1, 12, 6, 4
UOM Requirements:
  • Must be a positive integer (whole number)
  • Must be greater than 0
  • Represents unit of measure multiplier
  • Examples: 1, 2, 3

​
CSV Structure Examples

​
Basic Category Import

Code,Name,Eaches,UOM
MEAT-BEEF,Beef Products,1,1
MEAT-PORK,Pork Products,1,1
PRODUCE-VEG,Fresh Vegetables,12,2
DAIRY-MILK,Milk Products,4,3

​
Categories with Different UOM

Code,Name,Eaches,UOM
BAKERY-BREAD,Bread & Baked Goods,6,1
PRODUCE-FRUIT,Fresh Fruit,12,2
SEAFOOD-FISH,Fresh Seafood,1,1
DELI-MEAT,Deli Meats,8,2

​
Mixed Create and Update

If these categories already exist, they will be updated: 
Code,Name,Eaches,UOM
MEAT-BEEF,Premium Beef Products,1,1
PRODUCE-VEG,Organic Vegetables,12,3
BAKERY-NEW,New Bakery Items,6,1
In this example:
  • MEAT-BEEF and PRODUCE-VEG will be updated (if they exist)
  • BAKERY-NEW will be created (if it doesn’t exist)

​
Business Rules

​
Category Code Uniqueness

Within CSV file:
  • Each code must appear only once in your CSV
  • Duplicate codes will cause validation errors
  • System checks for duplicates before import
In system:
  • System searches for existing categories by code
  • If found: Updates the existing category
  • If not found: Creates a new category

​
Create vs Update Behavior

The import can create new categories or update existing ones: Finding existing categories:
  • System searches by Code to find matching categories
If category exists:
  • Updates the category with new data from CSV
  • Updates Name, Eaches, and UOM values
  • Keeps the same category ID
If category doesn’t exist:
  • Creates new category
  • Assigns new category ID
  • Sets all values from CSV

​
Field Validation

All fields are validated before import:
  • Code Format: Must match pattern (alphanumeric and allowed special characters)
  • Code Length: Maximum 32 characters
  • Name Length: Maximum 64 characters
  • Eaches: Must be positive integer greater than 0
  • UOM: Must be positive integer greater than 0
  • Required Fields: All four fields must be present and non-empty

​
Best Practices

​
Preparing Your CSV

CSV Preparation Tips

  • Use UTF-8 encoding to support special characters
  • Keep category codes consistent and descriptive
  • Use PascalCase for column headers
  • Test with a small file first (5-10 categories)
  • Validate your CSV in a spreadsheet before uploading
  • Remove empty rows and columns
  • Ensure all four columns are present for every row

​
Category Code Naming

Recommended patterns: 
Code,Name,Eaches,UOM
MEAT-BEEF,Beef Products,1,1
MEAT-PORK,Pork Products,1,1
MEAT-POULTRY,Poultry Products,1,1
PRODUCE-VEG,Fresh Vegetables,12,2
PRODUCE-FRUIT,Fresh Fruit,12,2
DAIRY-MILK,Milk Products,4,3
DAIRY-CHEESE,Cheese Products,1,1
Benefits of hierarchical codes:
  • Easy to filter and search
  • Groups related categories
  • Scales well as catalog grows
  • Maintains consistent organization

​
Understanding Eaches and UOM

Eaches represents the number of individual units in a package:
  • 1 eache = sold individually (e.g., single steak)
  • 12 eaches = dozen pack (e.g., 12-pack of apples)
  • 6 eaches = six-pack (e.g., 6-pack of yogurt)
UOM (Unit of Measure) is a multiplier:
  • 1 = base unit
  • 2 = double the base unit
  • 3 = triple the base unit
Example calculation: If an item has:
  • Eaches: 12
  • UOM: 2
  • Then: 1 case = 12 individual units × 2 = 24 total items

​
Data Quality

Before importing:
  • Verify category codes are unique and descriptive
  • Ensure names clearly describe the category
  • Check that eaches values accurately reflect package sizes
  • Confirm UOM multipliers are correct
  • Validate all values are positive integers

​
Large Imports

For importing many categories:
  • Break into smaller batches (50-100 categories per file)
  • Test with one batch before importing all
  • Monitor results carefully for each batch
  • Keep a master spreadsheet of all categories

​
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 four column headers are present: Code, Name, Eaches, UOM
  • Verify exact spelling and PascalCase format
  • All four columns are required (no optional fields)
Invalid code format: 
❌ "MEAT/BEEF&PORK*" - Contains invalid character (*)
✅ "MEAT-BEEF&PORK" - Valid characters only
Code too long: 
❌ "MEAT-BEEF-PREMIUM-GRASS-FED-ORGANIC-LOCAL" - Exceeds 32 characters
✅ "MEAT-BEEF-PREMIUM" - Within 32 character limit
Name too long:
  • Maximum 64 characters for category name
  • Shorten descriptive names if needed
Invalid numeric values: 
❌ Eaches: "0" - Must be greater than 0
❌ Eaches: "-5" - Must be positive
❌ Eaches: "1.5" - Must be whole number (integer)
✅ Eaches: "12" - Valid positive integer
Duplicate codes in CSV: 
Row 2: MEAT-BEEF
Row 5: MEAT-BEEF  ❌ Duplicate code error
  • Each code must appear only once
  • Check for accidental duplicates
  • Remove or rename duplicate entries

​
Data Validation Issues

Common data errors: Empty required fields:
  • System requires all four fields for every row
  • Check for empty cells in CSV
  • Verify no rows have missing data
Whitespace issues:
  • Leading/trailing spaces in codes may cause issues
  • Trim whitespace from all fields
  • Use spreadsheet TRIM function if needed

​
Import Failures

If individual categories fail during import:
  1. Review the error message for that category
  2. Common causes:
    • Database constraint violation
    • Invalid data despite format validation passing
    • Network or server error
  3. Fix the issue in your CSV
  4. Re-import only the failed records

​
Partial Success

If some categories import but others fail:
  • Successful imports are NOT rolled back
  • Failed categories can be fixed and re-imported
  • Check if existing categories were updated correctly
  • Verify new categories were created with correct values
The import handles each category independently. One failed category won’t prevent others from succeeding.

​
After Import

​
Verify Imported Data

After successful import:
  1. Navigate to Product → Categories list
  2. Search for imported categories by code or name
  3. Open category details to verify:
    • Category code is correct
    • Name is accurate
    • Eaches value is correct
    • UOM multiplier is correct

​
Fix Issues

If you find issues after import:
  • Edit categories directly in the UI
  • Update names, eaches, or UOM values
  • Re-import with corrected data (will update existing)
  • No need to delete and re-import

​
Next Steps

After importing categories:
  • Assign categories to items
  • Verify UOM calculations are correct
  • Test ordering and inventory tracking
  • Train staff on category usage

​
Common Questions

Q: Can I import categories with the same name but different codes? A: Yes, category names don’t need to be unique. Only codes must be unique. Q: What happens if I import a category that already exists? A: The system updates the existing category with the new values from your CSV. Q: Can I delete categories via CSV import? A: No, CSV import only creates or updates categories. Use the UI to delete categories. Q: What if I need to change a category code? A: Category codes cannot be changed via import. Create a new category with the desired code, reassign items, then delete the old category. Q: Are there default categories I should create? A: Category structure depends on your business. Common patterns include grouping by department (MEAT, PRODUCE, DAIRY) or product type. Q: Can eaches and UOM be decimal numbers? A: No, both must be positive integers (whole numbers greater than 0).