Historical Transaction Import

Use Import History in Import Center when you are bringing in a substantial set of older records. The import is staged and reviewed before anything is saved.

Choose the right mode #

Reporting-only history #

Choose Reporting-only history when older rows should be available in reports and transaction review without changing current balances or budget math. This is usually the right first choice when your account balances are already correct.

Full ledger import #

Choose Full ledger import when the older rows should become normal ledger transactions. They affect account balances, budget history, and reports, so review this mode carefully.

Start with a file, one-time setup, or the history template #

Import History accepts CSV or tab-delimited data. For a one-time migration, choose Download History Template in the import panel. The built-in template stages without a saved Source Profile.

Its headings must stay in this order:

date, type, account, transfer_account, category, label, payee, note, amount, external_id

• Date uses YYYY-MM-DD.
• Type is expense, income, deposit, refund, transfer, growth, or loss.
• Account must exactly match an existing Common Cents account when the file supplies one.
• Categories and labels are optional. When source values do not match Common Cents, you can match an existing value or leave them unmapped.
• Transfer rows need a different existing account in transfer_account.
• Categories and labels are never created automatically. The optional categorization review can open the normal creation flow when you explicitly need a new one.

For a different layout, choose Set Up This File directly in History Import. Map its columns, then either Use for This History Import or save it as a reusable Source Profile. One-time setup is not saved in your file.

When a profile does not map an Account column, choose one receiving account in History Import. If the profile does map Account, its source values remain authoritative and can support a multi-account import.

Import the history #

1. Open Import Center, then choose Import History.
2. Open or paste the CSV or tab-delimited data. You can use the built-in template, a matching Source Profile, or set up this file once.
3. Choose the destination account when the profile does not map one, then choose Reporting-only history or Full ledger import.
4. Open Review Payee Choices. The review remains available even when the file has validation errors, so you can see every issue before importing.
5. Resolve unmatched imported payees:
   • In reporting-only mode, choose Use a Common Cents payee or Leave as imported text.
   • In full-ledger mode, choose a Common Cents payee. Search is punctuation-insensitive, so Kohls can find Kohl's; you can also use a new name.
   • A new payee is only created when you choose the final import action. These one-time choices do not create reusable Source Profile recognition rules.
6. Optionally open Improve categorization for unmatched categories or labels. Matching is optional; leave a value unmapped when historical grouping is not useful enough to change your current budget structure.
7. Fix any listed validation issues in the source file or Source Profile. The final Import Historical Transactions action stays disabled until the file has valid rows and no blocking issues.
8. Inspect the ready rows and choose Import Historical Transactions.
9. Confirm the import. Common Cents creates a backup copy of the current file before it writes any history. If creating that backup is cancelled or fails, the import does not run.

When source data is retained, Common Cents keeps the mapped values and row provenance for later review. For the built-in template, choose whether to retain those values just for that one import. The built-in template has no saved Source Profile revision.

Avoiding duplicates #

Map or provide an external ID when the source system has a stable transaction identifier. Rows that Common Cents imported before with the same source profile and account are excluded by default; you can intentionally include them again. Same-date-and-amount overlaps are marked as possible duplicates and remain in the import for review.

Bank-history limitations #

Basic bank exports often have dates, descriptions, and amounts but no reliable category data. They can still be imported: Common Cents infers expense or income from the amount sign and leaves categories unmapped. They remain available in historical reporting (and affect ledger balances only in Full ledger mode), but they do not contribute to category or budget analysis unless you explicitly match category values during review.

Important behavior #

• Reporting-only history appears in reports and transaction review but does not affect balance or budget calculations.
• Full ledger history creates normal transactions and does affect balance and budget calculations.
• No staged rows or drafted payees are saved until you choose the final import action.

Manage a completed import #

Import Center lists completed history imports below your Source Profiles. Each batch shows its source file, mode, row count, and any payees created during the import. Choose Details to see the Source Profile revision (when one was used), review warnings, mapped retained values, and row provenance.

If mapped source values were retained, Purge Retained Source Data permanently removes those raw values. This cannot be undone. The imported transactions, completed batch summary, warnings, duplicate fingerprints, and provenance links remain available.

Choose Delete Import to remove every row from one batch. For a full-ledger batch, that removes the corresponding live transactions; for a reporting-only batch, it removes only the reporting history. A payee created by the batch is removed only if no remaining transactions use it. Use the backup made before the import if you need to restore the file to its earlier state.