Skip to main content

CSV Import

Use CSV import to stage transactions, review potential duplicates, and then confirm what should be written to your data.

Prerequisites​

  • CSV import is only available when AI is configured for your Cashlytics instance (OPENAI_API_KEY must be set).
  • You must be signed in.
  • You must select an account you own before uploading.
  • Your file must be a CSV and include a header row plus at least one data row.

Expected CSV Format​

Cashlytics accepts comma-separated and semicolon-separated CSV files.

Required fields​

  • booking_date
  • amount
  • currency

Optional fields​

  • description
  • counterparty
  • sender_account
  • receiver_account
  • balance_after_booking
  • reference

Practical header example​

booking_date;amount;currency;description;counterparty;sender_account;receiver_account;balance_after_booking;reference

Header names and normalization behavior​

  • Header matching is tolerant: it normalizes case, spaces, separators, and diacritics.
  • Common aliases are accepted (for example localized bank export headers).
  • If automatic mapping fails, you must provide a manual header mapping before the import can continue.

Row parsing behavior you should know​

  • Dates are parsed from YYYY-MM-DD and DD-MM-YYYY styles (also with / or . separators).
  • Amounts are normalized to decimal values (different thousand/decimal separator styles are handled).
  • Currency is normalized to uppercase.
  • If description is empty, Cashlytics falls back to counterparty; if both are empty, it uses Imported row N.
  • Empty lines are ignored.

Workflow​

  1. Select the target account and upload your CSV file.
  2. Cashlytics validates and stages rows into an import session (no transactions are committed yet).
  3. Reconciliation runs to detect potential duplicates against existing income/expense entries in the same account.
  4. Resolve each detected conflict.
  5. Review staged rows and remove rows you do not want to import.
  6. Confirm import to write approved rows into Income/Expenses.

Conflict Handling Decisions​

For each conflict, choose one of these actions:

  • Keep both: the imported row is inserted as a new transaction.
  • Replace existing record: the matched existing transaction is updated with imported values.
  • Skip imported row: the imported row is not written.

Important behavior:

  • You must resolve all conflicts before confirmation is allowed.
  • If a row is removed during review, it is excluded from import and its related conflict entry is cleared.

Review and Confirmation Behavior​

  • Review shows staged rows in import order with key values (description, amount, currency).
  • Removing a row excludes it from final commit.
  • Confirmation is blocked if there are unresolved conflicts.
  • Confirmation is blocked if no rows remain.
  • Confirmation is irreversible.

Limits​

  • Maximum file size: 1 MB.
  • Maximum data rows per file: 5000.
  • File must not be empty.

AI Dependency and Implications​

  • If AI is not configured, the CSV import page is unavailable.
  • Duplicate detection always includes deterministic exact matching.
  • AI is used for near-match suggestions; if AI output is invalid or fails, Cashlytics falls back to exact matching only.
  • AI suggestions are never auto-committed: you still choose the final decision per conflict.

Common Errors and What to Check​

  • "CSV file is empty": verify the file has content and not only headers/blank lines.
  • "Unsupported file type": export a real CSV file and re-upload.
  • "CSV file too large": reduce file size below 1 MB.
  • "CSV exceeds row limit (5000)": split the file into smaller batches.
  • "CSV header mapping missing required fields": ensure booking_date, amount, and currency can be matched (or provide manual mapping).
  • "Row X parsing failed" / validation errors: check date format, numeric amount, and required values in that row.
  • "You must resolve all conflicts before confirmation": pick a decision for every listed conflict.
  • "Import session not found" or access errors: retry from the import page with the correct signed-in account.