## Importing Expenses via CSV

Alpha Insights provides a powerful CSV import feature for bulk expense entry. This is ideal for migrating from other systems, importing from accounting software, or adding many expenses at once.

### When to Use CSV Import

- Initial Setup: Importing historical expenses when first configuring Alpha Insights
- Migration: Moving from spreadsheets or other expense tracking systems
- Bulk Entry: Adding multiple expenses faster than manual entry
- Integration: Importing data exported from accounting software
- Recurring Imports: Regular imports if you maintain expenses elsewhere

### Accessing the Import Interface

1. Go to Alpha Insights → Expense Manager
2. Click Import Expenses from the navigation
3. You'll see two tabs:
   - CSV Import: Upload a CSV file
   - Manual Bulk Entry: Paste data or manually enter multiple expenses

### CSV Import Process

#### Step 1: Prepare Your Data

Your CSV file should include the following columns:

Required Columns:

- `title` - Expense name/description
- `amount` - Numeric amount (no currency symbols or thousands separators)
- `date_paid` - Date in YYYY-MM-DD format

Optional Columns:

- `currency` - 3-letter currency code (e.g., USD, GBP, EUR) - defaults to store currency if omitted
- `expense_category` - Category name or ID (will be created if doesn't exist)
- `supplier` - Supplier name or ID (will be created if doesn't exist)
- `reference` - Invoice or reference number

Note: CSV import currently supports one-time expenses only. For recurring expenses, use the manual Add Expense interface.

#### Step 2: Format Your CSV File

CSV Format Requirements:

- First row must contain column headers (case-sensitive)
- Use commas as delimiters
- Enclose fields containing commas in double quotes
- Use UTF-8 encoding
- Date format: YYYY-MM-DD (e.g., 2024-10-23)
- Amount format: Numeric only, use period for decimals (e.g., 2500.50)

Example CSV Content:

    title,amount,currency,date_paid,expense_category,supplier,reference
    Office Rent,2500,USD,2024-01-01,Operating Expenses,Property Management Co,Invoice-2024-01
    Adobe Creative Cloud,52.99,USD,2024-01-15,Software & Tools,Adobe,SUB-2024-01
    Marketing Campaign,1500,USD,2024-01-20,Marketing,Agency XYZ,Campaign-Q1-2024
    "Office Supplies, Various",145.32,USD,2024-01-25,Operating Expenses,Office Supply Co,Receipt-012524
    Employee Salary,3500,USD,2024-01-31,Personnel,,Payroll-Jan-2024

#### Step 3: Upload Your CSV

1. Click the CSV Import tab
2. Click Choose File or drag and drop your CSV file
3. The system will validate your file format
4. If errors are found, you'll see specific error messages
5. If validation passes, you'll see a preview of what will be imported

#### Step 4: Review Preview

The preview shows:

- Number of expenses to be imported
- Sample of first few expenses
- Any warnings (e.g., categories that will be auto-created)
- Total amount to be imported

#### Step 5: Confirm Import

1. Review the preview carefully
2. If everything looks correct, click Import Expenses
3. The system will process your import
4. You'll see a progress indicator
5. When complete, you'll see a success message with:
   - Number of expenses created
   - Any errors or warnings
   - Categories created (if any)
   - Suppliers created (if any)

### Manual Bulk Entry

For smaller imports or when you don't have a CSV file ready, use the Manual Bulk Entry feature:

#### Using Manual Bulk Entry:

1. Click the Manual Bulk Entry tab
2. You'll see a form with fields for multiple expenses
3. Enter each expense:
   - Title
   - Amount
   - Date
   - Category (dropdown with create option)
   - Supplier (dropdown with create option)
   - Reference
4. Click Add Another Row to add more expenses
5. Click Remove to delete a row
6. When all expenses are entered, click Import All
7. Review and confirm

Benefits of Manual Bulk Entry:

- No need to create a CSV file
- Dropdown selection for categories and suppliers
- Option to create new categories/suppliers inline
- Date picker for easy date selection
- Real-time validation

### Category and Supplier Handling

#### Auto-Creation

When you import expenses with categories or suppliers that don't exist:

- The system will automatically create them
- New categories are created as top-level (no parent)
- New suppliers are created with just the name
- You'll see a message listing what was created
- You can edit these later in Manage Taxonomies

#### Matching Existing Taxonomies

The import system tries to match categories and suppliers by:

1. ID: If you provide numeric IDs, it uses exact matches
2. Name: If you provide names, it searches for exact name matches (case-sensitive)
3. Create: If no match found, creates new taxonomy term

Best Practice: Use consistent naming to avoid duplicate categories/suppliers. Review the Manage Taxonomies page after importing to merge any duplicates.

### Common Import Scenarios

#### Scenario: Importing from QuickBooks

1. Export expense report from QuickBooks to CSV
2. Open CSV in Excel or Google Sheets
3. Map QuickBooks columns to Alpha Insights columns:
   - Memo → title
   - Amount → amount
   - Date → date_paid
   - Category → expense_category
   - Vendor → supplier
   - Ref No → reference
4. Save as CSV with correct column headers
5. Import into Alpha Insights

#### Scenario: Importing from Excel Spreadsheet

1. Open your expense tracking spreadsheet
2. Add a header row with Alpha Insights column names
3. Ensure dates are in YYYY-MM-DD format
4. Ensure amounts have no currency symbols or thousands separators
5. Save as CSV (not XLSX)
6. Import into Alpha Insights

#### Scenario: Importing Historical Data

When importing years of historical expenses:

1. Break into smaller files (e.g., by year or quarter) for easier management
2. Import oldest data first
3. Review each import before proceeding to next
4. Verify totals match your source data
5. Use the export feature to create a backup after each successful import

### Troubleshooting Import Errors

#### Error: "Invalid CSV format"

Cause: File is not a proper CSV or has encoding issues

Solution:

- Ensure file is saved as CSV (not XLSX or other format)
- Use UTF-8 encoding
- Try opening in a text editor to verify it's comma-delimited
- Re-save from Excel using "CSV UTF-8 (Comma delimited)" option

#### Error: "Missing required column: title"

Cause: Column header is missing or misspelled

Solution:

- Verify first row has exact column names: title, amount, date_paid
- Column names are case-sensitive
- No extra spaces before/after column names

#### Error: "Invalid date format in row X"

Cause: Date is not in YYYY-MM-DD format

Solution:

- Change all dates to YYYY-MM-DD format (e.g., 2024-10-23)
- In Excel, format the date column as Text before entering dates
- Use Excel formula: `=TEXT(A1,"YYYY-MM-DD")` to convert dates

#### Warning: "Invalid date format, used today's date instead"

Cause: Date couldn't be parsed but import continued using current date

Solution:

- Check the import summary for which expenses had this issue
- Edit those expenses individually to set correct dates
- Or fix dates in CSV and re-import

#### Error: "Amount must be positive number"

Cause: Amount contains non-numeric characters or is negative

Solution:

- Remove currency symbols ($, £, €)
- Remove thousands separators (commas)
- Use period for decimal separator (not comma)
- Ensure all amounts are positive
- Format: 2500.50 not $2,500.50

#### Warning: "Category 'X' not found, created new category"

Not an error: System created a new category automatically

Action:

- Review new categories in Manage Taxonomies
- Edit to assign parent categories if needed
- Merge duplicates if category was misspelled

### Import Limits and Performance

File Size Limits:

- Maximum file size: 5MB
- Maximum rows per import: 5,000 expenses
- For larger imports, split into multiple files

Processing Time:

- Small imports (< 50 expenses): Nearly instant
- Medium imports (50-500 expenses): 5-15 seconds
- Large imports (500-5000 expenses): 30-90 seconds

Performance Tips:

- Import during off-peak hours for large imports
- Don't navigate away during import process
- Split very large imports into batches
- Pre-create categories and suppliers to speed up processing

### Post-Import Verification

#### After Importing:

1. Check Counts: Verify total expense count matches your expectations
2. Review Categories: Check Manage Taxonomies for any duplicates
3. Spot Check: View a few random expenses to verify data accuracy
4. Check Totals: Compare total amounts to source data
5. Review Dashboard: Check that metrics updated correctly
6. Test Filters: Try filtering by category, date, etc. to ensure data is accessible

#### If Something Went Wrong:

- Bulk Delete: Use Manage All Expenses to filter and bulk delete incorrect imports
- Re-Import: Fix your CSV file and import again
- Manual Edit: For small issues, edit individual expenses

### Exporting for Backup

After successful import, create a backup:

1. Go to Manage All Expenses
2. Click Export All
3. Save the CSV file
4. This serves as a backup and template for future imports

### Best Practices for CSV Imports

#### Before Importing:

- Test with a small sample file first (5-10 expenses)
- Clean your data - remove duplicates, fix formatting issues
- Standardize category and supplier names
- Back up existing expense data

#### During Import:

- Review the preview carefully before confirming
- Watch for auto-created categories/suppliers
- Note any warnings or errors
- Don't navigate away until complete

#### After Importing:

- Verify data accuracy
- Clean up taxonomies
- Add attachments to imported expenses if needed
- Update any expenses that need corrections
- Export a backup

### CSV Template

Here's a template you can copy/paste to get started:

    title,amount,currency,date_paid,expense_category,supplier,reference
    Sample Expense 1,100.00,USD,2024-01-01,Operating Expenses,Supplier A,INV-001
    Sample Expense 2,250.50,USD,2024-01-15,Marketing,Supplier B,INV-002
    Sample Expense 3,75.25,USD,2024-01-20,Software & Tools,Supplier C,SUB-2024-01

To use this template:

1. Copy the above code
2. Paste into a text editor or Excel
3. Replace sample data with your actual expenses
4. Save as CSV
5. Import into Alpha Insights

### Advanced: Programmatic Import

For developers or advanced users, expenses can also be imported via:

- WordPress REST API: Alpha Insights provides REST endpoints for expense creation
- Direct Database Access: Create expense posts programmatically with proper metadata
- Integration Scripts: Connect to accounting software APIs and sync to Alpha Insights

Note: Programmatic import requires developer knowledge. See the Developer Documentation for API details.