Skip to content

Bulk Order Item Import (CSV) Documentation

Menu Location: Orders > Add Items to Orders CSV

Access Level: Manager and above

Last Updated: 2026-03-01

Overview

The Bulk Order Item Import tool allows you to add products to multiple customer orders simultaneously using a CSV file upload. This is particularly useful for seasonal additions, promotional items, or fulfillment corrections that affect many customers at once.

Primary Functions:

  • Upload CSV file to add items to multiple orders
  • Add same product to many customers at once
  • Correct missing items across multiple orders
  • Distribute promotional products to specific customer groups
  • Bulk add seasonal or limited-time offerings

Page Layout

Header Section

  • Page Title: "Add Items to Orders CSV"
  • Instructions: Template guidance and field requirements
  • Download Template Link: Sample CSV file with correct format

Upload Section

  • Choose File Button: Select CSV file from your computer
  • File Preview: Shows first few rows after selection
  • Validation Messages: Displays errors or warnings before processing

Processing Section

  • Process Button: Execute the bulk import
  • Progress Indicator: Shows processing status
  • Results Summary: Displays success/failure counts

CSV File Format

Required Columns

The CSV must include these exact column headers:

Required Fields:

  • customer_id - Unique customer ID number (from customer detail page)
  • product_id - Product ID number (from product list)
  • quantity - Number of items to add (positive integer)

Optional Fields:

  • order_date - Specific delivery date (YYYY-MM-DD format)
  • price_override - Custom price for this item (decimal)
  • note - Internal note about this addition

CSV Format Rules

  1. First row must be headers (column names)
  2. Each row = one item addition to one customer's order
  3. Use commas to separate columns
  4. No blank rows in the middle of data
  5. Save as .csv format (not Excel .xlsx)

Example CSV

customer_id,product_id,quantity,order_date,note
12345,789,2,2026-03-15,Promotional addition
12346,789,1,2026-03-15,Promotional addition
12347,789,2,2026-03-15,Promotional addition

How to Create Your CSV File

Method 1: Download Template

Steps:

  1. Click "Download Template" link on page
  2. Open downloaded file in Excel or Google Sheets
  3. Fill in your data following the format
  4. Save as CSV format (.csv extension)
  5. Upload to the import page

Method 2: Export from Customer Filter

Steps:

  1. Go to Customers page
  2. Apply filters to select target customers (e.g., "Active" + "Route 5")
  3. Export customer list with IDs
  4. Open export in Excel
  5. Add product_id and quantity columns
  6. Remove unnecessary columns
  7. Save as CSV

Method 3: Create from Scratch

Steps:

  1. Open Excel or Google Sheets
  2. Create column headers: customer_id, product_id, quantity
  3. Add one row per customer/product combination
  4. Save as CSV format

Finding Customer and Product IDs

Finding Customer ID

Method 1:

  1. Go to Customers page
  2. Search for customer
  3. Click customer name to open detail page
  4. Customer ID appears in header (e.g., "Customer #12345")
  5. Click ID to copy to clipboard

Method 2:

  1. Export customer list from Customers page
  2. CSV includes customer_id column
  3. Use these IDs in your bulk import file

Finding Product ID

Method 1:

  1. Go to Products page
  2. Find product in list
  3. Click product name to edit
  4. Product ID appears in URL: product-edit.php?id=789
  5. Or look for "Product ID: 789" on edit page

Method 2:

  1. Export product list
  2. CSV includes product IDs
  3. Reference for your import file

Upload and Processing

Upload Your CSV File

Steps:

  1. Click "Choose File" button
  2. Select your prepared CSV file
  3. System validates file format
  4. Preview shows first 5-10 rows
  5. Review for accuracy

Validation Checks

Before processing, system checks:

  • Valid CSV format - File structure is correct
  • Required columns - customer_id, product_id, quantity present
  • Valid customer IDs - Customers exist in database
  • Valid product IDs - Products exist and are active
  • Valid quantities - Positive integers only
  • Valid dates - Proper date format if provided
  • Duplicate entries - Warns if same customer/product appears multiple times

Process the Import

Steps:

  1. Review validation results
  2. Fix any errors highlighted in red
  3. Click "Process Import" button
  4. System processes each row
  5. Progress bar shows completion
  6. Results summary displays

Processing Time:

  • Small files (under 100 rows): 5-15 seconds
  • Medium files (100-500 rows): 15-60 seconds
  • Large files (500+ rows): 1-3 minutes

Understanding Results

Success Summary

After processing, you'll see:

  • Total Rows Processed: Number of rows in CSV
  • Successful Additions: Items successfully added
  • Skipped/Errors: Rows that failed
  • Error Details: Specific issues for each failed row

Common Success Messages

  • "Successfully added 2x Product Name to Order #12345"
  • "150 items added across 75 orders"
  • "All items processed successfully"

Common Error Messages

"Customer ID not found: 99999"

  • Customer doesn't exist or ID is incorrect
  • Check customer ID is accurate
  • Customer may have been deleted

"Product ID not found: 888"

  • Product doesn't exist or is deleted
  • Verify product ID is correct
  • Product may be inactive

"No open order for customer 12345 on 2026-03-15"

  • Customer has no order for specified date
  • Check customer's delivery schedule
  • Order may need to be created first

"Invalid quantity: abc"

  • Quantity must be a number
  • Check for text in quantity column
  • Ensure no special characters

"Duplicate entry detected: customer 12345, product 789"

  • Same customer/product appears twice in CSV
  • Remove duplicate rows
  • Or combine quantities into single row

Common Use Cases

Use Case 1: Add Promotional Item to Route Customers

Goal: Give free promotional item to all customers on specific route

Steps:

  1. Go to Customers page
  2. Filter by Route (e.g., "Route 5")
  3. Filter by Status: Active
  4. Export customer list with IDs
  5. Open export in Excel
  6. Add columns: product_id (promotional item), quantity (1)
  7. Add order_date (next delivery date)
  8. Save as CSV
  9. Upload to Bulk Import page
  10. Review validation
  11. Process import
  12. Verify items added by checking a few orders

Example: Adding free seasonal fruit sample to 150 customers on Route 5 for March 15th delivery.

Use Case 2: Correct Missing Items Across Multiple Orders

Goal: Fix packing error where item was omitted from many orders

Steps:

  1. Identify affected orders (date range, route, etc.)
  2. Export order list or customer list for that date
  3. Create CSV with customer_id, missing product_id, quantity
  4. Include order_date for specific delivery
  5. Add note: "Correction - missing from original order"
  6. Upload and process
  7. Items automatically added to affected orders

Tips:

  • Add note explaining the correction
  • Consider emailing affected customers
  • Update packing procedures to prevent recurrence

Use Case 3: Seasonal Addition Campaign

Goal: Add seasonal product to all active subscribers

Steps:

  1. Go to Customers page
  2. Filter: Status = Active, Has subscription = Yes
  3. Export customer list
  4. Open in Excel
  5. Add product_id for seasonal item
  6. Add quantity (e.g., 1 for each customer)
  7. Leave order_date blank to add to next scheduled order
  8. Save as CSV and upload
  9. Process import
  10. Review results

Example: Adding pumpkins to all active customers' October orders.

Use Case 4: VIP Customer Special Addition

Goal: Add bonus item to tagged VIP customers

Steps:

  1. Go to Customers page
  2. Filter by Tag: "VIP" (or similar)
  3. Export customer list with IDs
  4. Create CSV with bonus product
  5. Set quantity based on VIP tier if applicable
  6. Upload and process

Use Case 5: Geographic-Specific Product Addition

Goal: Add regional product to customers in specific area

Steps:

  1. Filter customers by state/zip code
  2. Export customer list
  3. Add regional product ID to CSV
  4. Process bulk addition
  5. Regional product now in those customers' orders

Troubleshooting

CSV File Won't Upload

Symptoms:

  • File selection fails
  • "Invalid file format" error
  • Upload button doesn't work

Solutions:

  1. Verify file is saved as .csv format (not .xlsx or .xls)
  2. Check file size - must be under 5MB
  3. Open file in text editor to verify it's true CSV
  4. Try re-saving file as CSV
  5. Check for special characters in data

Common Causes:

  • File saved as Excel format instead of CSV
  • File corrupted during download/save
  • Browser security blocking upload

Validation Errors

Symptoms:

  • Multiple rows flagged as errors
  • "Missing required column" message
  • Customer/Product ID errors

Check:

  1. Column headers match exactly (case-sensitive)
  2. customer_id column contains valid numbers
  3. product_id column contains valid numbers
  4. quantity column contains positive integers
  5. No blank rows in middle of data
  6. First row is headers, data starts row 2

Some Items Not Added

Symptoms:

  • Results show partial success
  • Some customers didn't receive item
  • "No open order" errors

Solutions:

  1. Review error details for specific issues
  2. Check if customers have orders for specified date
  3. Verify customers are active/not cancelled
  4. Check if order is already shipped (can't modify)
  5. Ensure order hasn't been cancelled

Common Causes:

  • Customer has no order for target date
  • Order already processed/shipped
  • Customer cancelled between export and import
  • Order date in past or too far in future

Duplicate Items Added

Symptoms:

  • Customer has 2x quantity of intended item
  • Same product appears twice in order

Check:

  1. Did you run import twice?
  2. Does CSV have duplicate rows for same customer?
  3. Did customer already have item in order?

Solutions:

  1. Go to individual orders and remove duplicate manually
  2. Or adjust quantities to correct amount
  3. Create note documenting the correction

Processing Takes Too Long

Symptoms:

  • Import seems stuck
  • Progress bar not moving
  • Browser timeout error

Solutions:

  1. For very large files (1000+ rows), split into smaller batches
  2. Process 500 rows at a time
  3. Ensure stable internet connection
  4. Don't close browser tab during processing
  5. If timeout occurs, check which rows processed before resubmitting remainder

If Problem Persists: Contact system administrator - may be server timeout setting issue

  • Customers - Export customer lists for import file creation
  • Products - Find product IDs for import
  • Orders - View individual orders after bulk additions
  • Order Contents Dump - Report to verify bulk additions
  • Create New Box - Alternative method for adding items to box types

Typical Workflow:

  1. Identify target customers (Customers page filters)
  2. Export customer list
  3. Prepare CSV with product additions
  4. Upload to Bulk Import page
  5. Verify results in Orders or Order Contents Dump report

Permissions & Access

Required Access Level: Manager or higher

Access Level Capabilities:

  • Manager: Can upload CSV and add items to orders
  • Administrator: All Manager capabilities + view detailed logs
  • Kiva Admin: All features + troubleshoot failed imports

Restricted Features:

  • Only Manager and above can access this page
  • Cannot modify shipped orders
  • Cannot add negative quantities (use other tools for removals)

Best Practices

File Preparation

  1. Always download and use the template - ensures correct format
  2. Start small - test with 5-10 rows before bulk processing
  3. Verify IDs - double-check customer and product IDs before uploading
  4. Use meaningful notes - document why items were added
  5. Keep backup of CSV - save file in case you need to reference or re-run

Data Validation

  1. Review preview carefully - catch errors before processing
  2. Check for duplicates - remove duplicate rows in Excel first
  3. Verify dates - ensure order dates match delivery schedules
  4. Confirm products are active - inactive products will fail
  5. Test with small batch - process 10-20 rows first to verify

Processing

  1. Process during off-peak hours - less system load
  2. Don't close browser - keep tab open while processing
  3. Save results summary - screenshot or export for records
  4. Review error details - fix issues for failed rows
  5. Verify in orders - spot-check a few orders to confirm additions

Communication

  1. Notify customers if adding promotional items
  2. Update packing team about bulk additions
  3. Document in admin notes why items were added
  4. Track campaign if promotional addition
  5. Follow up on errors - resolve failed additions

Things to Avoid

  • Don't upload files with thousands of rows without testing first
  • Don't process same file twice (creates duplicates)
  • Don't add items to shipped orders (will fail)
  • Don't use Excel formulas in CSV (export values only)
  • Don't forget to specify order_date if targeting specific delivery

Quick Reference Card

Task Action/Location
Download CSV template Click "Download Template" link on page
Find customer ID Customer detail page header or export customer list
Find product ID Product edit page URL or export product list
Upload CSV file Click "Choose File" button, select file
Fix validation errors Review error messages, update CSV, re-upload
Process import Review preview, click "Process Import"
Check results View success/error summary after processing
Verify additions Go to Orders page, check affected customer orders
Add promotional item to route Filter customers by route, export, add product_id
Correct missing items Create CSV with affected customers, product, date

FAQs

How many items can I add at once?

You can process several thousand rows, but it's recommended to batch process 500 rows at a time for better performance and easier troubleshooting.

Can I add different products to different customers in one file?

Yes! Each row can have a different product_id. One customer can have multiple rows for different products.

What happens if I upload the same file twice?

The items will be added twice, creating duplicates in orders. Always verify before processing and avoid running the same import multiple times.

Can I remove items using this tool?

No, this tool only adds items to orders. To remove items, you must edit individual orders manually or use a different bulk tool.

Will customers be notified when items are added?

No, items are added silently to orders. If you want to notify customers, send a separate email explaining the addition.

What if the customer doesn't have an order for the specified date?

The import will fail for that customer with a "No open order" error. You can either create orders first or omit the order_date to add to their next scheduled order.

Can I add items to past orders?

No, you cannot modify orders that have already been shipped or are in the past. Only open/future orders can be modified.

How do I add the same item to all active customers?

Filter customers by Status: Active, export the list, add the product_id and quantity columns to all rows, then upload.

What if I make a mistake?

If you process the wrong file, you'll need to manually remove the incorrect items from affected orders. There's no "undo" function, so always verify your CSV before processing.

Can I override the price for bulk-added items?

Yes, include a price_override column in your CSV with the custom price for that item.

Change Log

2026-03-01

  • Initial documentation created
  • All sections completed following template structure

End of Documentation

For additional help, contact your system administrator or Kiva Logic support.