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 (.csv, or .txt with CSV content) and include a header row plus at least one data row.
  • Rows are sent to OpenAI for the near-duplicate check, so only import data you are comfortable sharing with that provider.

Expected CSV Format​

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

Required fields​

  • booking_date
  • amount

Optional fields​

  • currency (empty or missing means the currency of the target account; rows in another currency are stored with the original amount)
  • description
  • counterparty
  • sender_account
  • receiver_account
  • balance_after_booking
  • reference

You can download a template with Download CSV template or open Show CSV structure on the upload step.

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, including German and Danish bank export headers:
    • booking_date: buchungsdatum, bogforingsdato, date
    • amount: betrag, belob
    • currency: valuta, waehrung
    • description: verwendungszweck, text, tekst, beskrivelse, beschreibung
    • counterparty: name, navn, gegenpartei
    • sender_account: absender, afsender
    • receiver_account: empfaenger, modtager
    • balance_after_booking: saldo, kontostand
    • reference: referenz, belegnummer
  • If automatic mapping fails, a Header mapping text field appears. Enter JSON that maps a Cashlytics field to your column header, for example {"booking_date": "Valutadatum", "amount": "Umsatz"}, and upload again.

Row parsing behavior you should know​

  • Files are read as UTF-8; if that fails, Windows-1252 is used.
  • Dates are parsed in YYYY-MM-DD and DD-MM-YYYY order with -, /, or . separators; two-digit years are accepted (70 and above mean 19xx).
  • Amounts are normalized to decimal values: thousand/decimal separators (. , ' space), currency symbols and codes, a trailing minus, parentheses (negative), and S/H debit/credit suffixes are handled.
  • Currency is normalized to uppercase.
  • Quoted fields may contain line breaks. Text values are truncated to 255 characters.
  • 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 and daily expenses in the same account (recurring expenses and transfers are not compared). Use Find possible duplicates to run it again.
  4. Resolve each detected conflict.
  5. Review staged rows and remove rows you do not want to import.
  6. Click Confirm and import to write approved rows (see below).

If the same file (by content) was already imported into the same account, you get a notice with the earlier import date.

How Rows Become Transactions​

The sign of amount decides the type:

  • amount >= 0: saved as income
  • amount < 0: saved as a daily (one-off) expense

The absolute amount is stored, the description becomes the source or description, and the note references the import session and row number. Imported expenses have no category; assign one afterwards. Rows in a currency other than the account currency are stored with their original amount.

Conflict Handling Decisions​

Exact duplicates have the same type, day, amount, and description (case and whitespace ignored). AI near-match suggestions only consider entries within 7 days (at most 200 per batch, 40 rows per AI call).

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: booking date, amount, currency, description, counterparty, sender/receiver account, balance after booking, and reference.
  • Rows can only be removed (Remove row), not edited.
  • Removing a row excludes it from final commit.
  • Confirmation is blocked until the duplicate check has run.
  • 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 (OpenAI gpt-4o) is used for near-match suggestions and receives the staged rows and nearby existing entries; if AI output is invalid or fails, Cashlytics falls back to exact matching only. If only some batches fail, a notice tells you how many rows were checked for exact duplicates only.
  • The CSV Import menu entry only appears when OPENAI_API_KEY is set.
  • 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 (.csv or .txt) 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 and amount can be matched (or provide manual mapping).
  • "Row X parsing failed" / validation errors: check date format, numeric amount, and required values in that row.
  • "Duplicate check has not run": click Find possible duplicates before confirming.
  • "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.