CSV Import Guide

Overview

The CSV Import feature allows you to bulk import financial transactions into your farm management system. This is ideal for:

• Migrating from another system
• Batch recording historical transactions
• Importing data from accounting software
• Updating multiple records simultaneously

What Can You Import?

The system supports importing the following transaction types:

Key Benefits

Getting Started

Step 1: Access the Import Feature

1. Log in to your farm management dashboard
2. Navigate to Financial → Import
3. Click "Import Transactions" button

Step 2: Download Template

Before creating your CSV file, download the official template:

1. Click "Download Template" button
2. Open the template in Excel, Google Sheets, or similar
3. Review the column headers and example data

Step 3: Prepare Your Data

Organize your transaction data according to the template format. See the CSV File Format section for detailed specifications.

CSV File Format

Required Columns

Every CSV file must include these columns (exact column names required):

Optional Columns (Recommended)

Transaction Type-Specific Fields

For SALE Transactions

Required additional fields:

• customerName - Customer who purchased
• productName - Product sold
• quantity - Quantity sold
• unitPrice - Price per unit

Optional fields:

• referenceNumber - Invoice/receipt number
• paymentMethod - Payment method used
• notes - Additional details

For EXPENSE Transactions

Required additional fields:

• category - Expense category
• supplierName or description - Who paid or what for

Optional fields:

• referenceNumber - Receipt/voucher number
• paymentMethod - Payment method
• allocatedFlockId - Specific flock to allocate to

For PURCHASE Transactions

Required additional fields:

• productName - Product/item purchased
• quantity - Quantity purchased
• unitPrice - Price per unit
• supplierName - Supplier name

Optional fields:

• category - Item category
• referenceNumber - Purchase order number

Example CSV Files

Example 1: Sales Import

recordType,date,amount,description,customerName,productName,quantity,unitPrice,paymentMethod
SALE,2026-01-15,17500.00,Egg sales,ABC Store,Large Eggs (Tray),50,350.00,MPESA
SALE,2026-01-16,14000.00,Egg sales,XYZ Market,Medium Eggs (Tray),40,350.00,CASH
SALE,2026-01-17,12000.00,Broiler sales,City Butchery,Live Broilers,20,600.00,BANK_TRANSFER

Example 2: Expenses Import

recordType,date,amount,description,category,supplierName,paymentMethod
EXPENSE,2026-01-10,45000.00,Feed purchase for January,Feed,Unga Feeds Ltd,BANK_TRANSFER
EXPENSE,2026-01-12,3500.00,Veterinary consultation,Veterinary,Dr. Kamau Clinic,MPESA
EXPENSE,2026-01-14,2500.00,Layer mash 70kg,Feed,Local Agro Vet,CASH

Example 3: Mixed Transactions

recordType,date,amount,description,customerName,supplierName,productName,quantity,unitPrice,category,paymentMethod
SALE,2026-01-20,21000.00,Egg sales,Eastleigh Market,,,Large Eggs (Tray),60,350.00,,MPESA
EXPENSE,2026-01-20,25000.00,Feed restocking,,,Pembe Feeds Ltd,,,Feed,BANK_TRANSFER
PURCHASE,2026-01-21,15000.00,Medication stock,,Agro Supplies,Tylosin 100g,30,500.00,Medication,CASH
SALE,2026-01-22,18000.00,Broiler harvest,Fresh Meats Ltd,,,Live Broilers,30,600.00,,MPESA

Import Process

Step-by-Step Import

1. Prepare CSV File

   • Format according to template
   • Save as CSV (UTF-8)
   • Double-check all required fields

2. Upload File

   • Click "Choose File" button
   • Select your CSV file
   • Click "Validate" button

3. Review Validation Results

   The system validates all data before import. Fix any errors shown in the validation report before proceeding.

   Validation checks:

   • ✅ Required fields present
   • ✅ Date formats correct (YYYY-MM-DD)
   • ✅ Amounts are valid numbers
   • ✅ Products exist in inventory
   • ✅ Customers/suppliers valid
   • ✅ No duplicate transactions

4. Fix Validation Errors

   If errors found:

   • Download error report
   • Fix issues in your CSV
   • Re-upload and validate again

5. Import Records

   Once validation passes:

   • Review import summary
   • Click "Import" button
   • System processes records
   • View import results

6. Verify Imported Data

   After import:

   • Check transaction list
   • Verify account balances
   • Review inventory changes
   • Confirm customer invoices created

Validation Rules

Date Validation

Format: YYYY-MM-DD

✅ Valid:

• 2026-01-15
• 2025-12-31
• 2026-02-28

❌ Invalid:

• 15/01/2026 (wrong format)
• 2026-13-01 (invalid month)
• 2026-02-30 (invalid date)

Amount Validation

Format: Decimal number

✅ Valid:

• 5000.00
• 15000
• 350.50

❌ Invalid:

• 5,000.00 (no commas)
• $350 (no currency symbols)
• Five thousand (no text)

Product Name Validation

The system matches by exact name:

• "Large Eggs (Tray)" ≠ "Large Eggs"
• Case-sensitive matching
• Must be active products

Customer/Supplier Validation

Customer and supplier names are matched flexibly:

• System creates new entries if not found
• Case-insensitive matching
• Trims whitespace automatically

Advanced Features

Automatic Flock Allocation

For flocks with cost allocation enabled:

recordType,date,amount,description,allocatedFlockId,category
EXPENSE,2026-01-15,25000.00,Feed for Layer Flock 1,flock-uuid-here,Feed

System automatically:

• ✅ Allocates expense to specified flock
• ✅ Updates flock cost tracking
• ✅ Calculates per-bird costs
• ✅ Includes in profitability reports

Inventory Synchronization

Sales and purchase imports automatically update inventory:

Sales:

• Reduces inventory quantity
• Records transaction in inventory history
• Updates cost of goods sold
• Triggers low-stock alerts if applicable

Purchases:

• Increases inventory quantity
• Updates average cost
• Records supplier information
• Creates inventory transaction

Payment Allocation

Payments can be automatically linked to invoices:

recordType,date,amount,description,referenceNumber,paymentMethod
PAYMENT,2026-01-20,15000.00,Payment for Invoice INV-001,INV-001,MPESA

System automatically:

• Links payment to matching invoice
• Marks invoice as paid/partially paid
• Updates customer balance
• Records payment history

Troubleshooting

Common Errors

"Required field missing"

Problem: One or more required columns are empty

Solution: Ensure every row has values for:

• recordType
• date
• amount
• description

"Invalid date format"

Problem: Date not in YYYY-MM-DD format

Solution: Convert dates to YYYY-MM-DD:

• Excel: Format Cells → Custom → yyyy-mm-dd
• Google Sheets: Format → Number → Custom date format

"Product not found"

Problem: Product name doesn't match inventory

Solution:

1. Check exact spelling and capitalization
2. Verify product exists in inventory
3. Create product first if new item

"Duplicate transaction detected"

Problem: Same transaction already exists

Solution:

• Check for duplicate rows in CSV
• Verify transaction wasn't already imported
• Use unique reference numbers

"Invalid amount"

Problem: Amount format incorrect

Solution:

• Remove currency symbols ($, KES, etc.)
• Remove commas from numbers
• Use decimal point (not comma) for decimals
• Ensure positive numbers (no negative signs)

Validation Failed Checklist

If import validation fails:

• Check all required columns present
• Verify date format (YYYY-MM-DD)
• Confirm amounts are valid numbers
• Check products exist in inventory
• Ensure no special characters in amounts
• Verify CSV encoding is UTF-8
• Check for hidden characters or spaces

Best Practices

Before Import

1. Backup Your Data

   Always backup your database before large imports. While imports are validated, backups provide safety.

2. Test with Small Batch

   Import 5-10 records first to verify format and catch any issues before processing hundreds of records.

3. Clean Your Data

   • Remove duplicate entries
   • Standardize naming (customers, products)
   • Verify all calculations
   • Check date ranges reasonable

4. Use Consistent Naming

   Standardize names across your CSV:

   • "ABC Store" not "ABC store" or "Abc Store"
   • "Large Eggs (Tray)" everywhere, not mixed formats

During Import

1. Review Validation Results Carefully

   Don't skip the validation step. Fix all errors before proceeding.

2. Check Import Summary

   Before final import, review:

   • Number of records to import
   • Total amounts
   • Transaction types breakdown
   • Date range

3. Monitor Progress

   For large imports:

   • Don't close browser window
   • Wait for completion message
   • Note any errors reported

After Import

1. Verify Key Totals

   Check that imported totals match expectations:

   • Total sales amount
   • Total expenses
   • Inventory quantities
   • Account balances

2. Review Sample Transactions

   Spot-check random imported records:

   • Customer names correct
   • Products linked properly
   • Amounts accurate
   • Dates correct

3. Check Related Records

   Verify automatic links created properly:

   • Sales created invoices
   • Payments linked to invoices
   • Inventory updated
   • Flock allocations applied

File Size and Limits

Import Limits

• Maximum rows: 1,000 transactions per file
• Maximum file size: 5 MB
• Supported encoding: UTF-8
• Timeout: 5 minutes processing time

Performance Tips

For large imports:

1. Split into smaller batches (500 records)
2. Import during off-peak hours
3. Process sequentially, not simultaneously
4. Allow 2-3 minutes between batches
5. Verify each batch before proceeding

Frequently Asked Questions

Can I import historical data?

Yes! You can import transactions from any date. The system properly handles:

• Past dates for historical records
• Future dates (not recommended)
• Multi-year imports

Will import overwrite existing data?

No. CSV import only creates new records. It never modifies or deletes existing transactions.

Can I import partial payment records?

Yes. Import payment records with partial amounts. System tracks remaining balances automatically.

How do I import transactions for multiple flocks?

Include the allocatedFlockId column with the flock UUID for each transaction. Or leave empty to allocate manually later.

Can I import in a different currency?

The system uses your organization's default currency. All amounts in CSV should be in that currency.

What happens if import fails halfway?

Only successfully validated records are imported. Failed records are reported in the error log. Fix and re-import failed records.

Get Support

Need help with CSV imports?

1. Check validation errors - Most issues are formatting problems
2. Review this guide - Common solutions documented above
3. Download template - Use the official template as reference
4. Contact support - Submit your CSV for review if stuck

Last updated: January 28, 2026