Historical Transaction Import

Historical Transaction Import is for bringing in a large amount of older transaction history at once. It is different from everyday transaction entry and different from Mass Transaction Entry.

Use it when you have years of transactions in a spreadsheet and want Common Cents to analyze the file, show problems, resolve payees, and then import the rows as one batch.

When to use it #

Historical import is a good fit when:

• you are starting with Common Cents and want old spending and income history available
• you already use Common Cents and want to add older records later
• you want reports, searches, payee history, category history, or income history across a longer date range

For day-to-day bank imports or a smaller batch of new transactions, use Bulk Entry or the normal Importing Transactions flow instead.

Choose the right import mode #

The page starts with Import Mode. Choose this before you upload the CSV.

Reporting-only history #

Choose Reporting-only history when the imported rows should appear in reports and transaction listings, but should not change account balances or budget math.

Reporting-only history:

• appears in transaction lists with a Reporting-only badge
• appears in reports and searches
• does not affect current account balances
• does not affect category available amounts
• can be deleted later by deleting the import batch

This is usually the safer mode for older history when your current account balances are already correct.

Full ledger import #

Choose Full ledger import when the imported rows should become normal ledger transactions.

Full ledger history:

• creates normal transactions in the file
• affects account balances
• affects budget and category history
• can significantly change historical reports and balances
• should be used only when the imported file is meant to become part of the real ledger

Use this mode carefully, especially in a file that already has current balances and recent transactions.

Before you start #

You need:

• at least one account in the file
• categories in the file
• a CSV file based on the historical import template
• enough time to review errors, warnings, and payee decisions before import

Common Cents requires a backup immediately before the import is committed.

1. Open Historical Transaction Import #

Open All Transactions, then choose Import History.

The Historical Transaction Import page shows:

• Import Mode
• Download CSV Template
• Upload CSV
• existing import batches, if this file already has historical imports

2. Download the CSV template #

Choose Download CSV Template.

Use that file as the shape for your import. The template is meant to make the import predictable and reduce cleanup after upload.

The important columns are:

• type: transaction type, such as expense, income, deposit, refund, transfer, growth, or loss
• account: the account where the transaction belongs
• transfer_account: for transfers, the other account involved in the transfer
• category: the category for expense, refund, and other categorized rows
• date: the transaction date
• payee: the payee name from your source data
• note: optional notes
• amount: the transaction amount
• labels: optional labels, when you want imported rows to carry label history
• external_id: an optional stable ID from the source file to help prevent duplicate imports

Income and deposit rows can be imported without a category. Expense rows usually need a category.

3. Fill the template from your spreadsheet #

Copy or transform your old transaction data into the template.

Before uploading, check these basics:

• dates are valid and consistently formatted
• account names match accounts in Common Cents
• category names match categories in Common Cents
• transfer rows include the other account in transfer_account
• amounts have the sign and value you expect
• duplicate source rows either share a deliberate external_id or have no external ID

If you are not sure whether a row should affect balances, choose Reporting-only history first.

4. Choose the import mode #

Back in Common Cents, choose either:

• Reporting-only history
• Full ledger import

Choose the mode before uploading the CSV so the analysis can apply the right rules.

5. Upload the CSV #

Choose Upload CSV and select the completed template file.

Common Cents analyzes the file before importing anything. At this stage, no rows have been saved.

6. Review the analysis summary #

After analysis, the page shows a summary with:

• total rows
• rows ready to import
• errors
• warnings
• date range
• payee matches
• counts by transaction type

If the summary does not match what you expected, stop and fix the CSV before importing.

7. Work through the review tabs #

The review area is split into tabs. Each tab header shows how many items need attention.

Payees #

Use Payees to resolve imported payee names that do not already match cleanly.

Depending on the import mode, unresolved payees can be handled by:

• matching an existing payee
• creating a new payee
• keeping the literal imported name for reporting-only history
• clearing the payee for full ledger rows when that is appropriate

Common Cents also shows possible matches when it can suggest them.

Errors #

Use Errors for blocking problems. Rows with errors cannot be imported until the CSV or payee decisions are fixed.

Common examples include missing required fields, unknown accounts, unknown categories, invalid dates, invalid amounts, or duplicate external IDs.

Warnings #

Use Warnings for non-blocking problems. These rows may still import, but you should review the warnings before committing the batch.

Warnings are useful for catching rows that look suspicious even when they are technically valid.

8. Download issues if needed #

If the analysis finds issues, choose Download Issues CSV.

This is useful when the import has many rows because you can fix the source spreadsheet, upload again, and repeat the review.

9. Create a backup and import #

When the file has no blocking errors and the ready-to-import count looks right, choose Create Backup and Import.

Common Cents saves a backup copy before committing the import. This is required because historical imports can add many rows at once, and full ledger imports can change balances and budget history.

After the backup step, Common Cents imports the rows and records the import as a batch.

10. Review the imported batch #

After import, the page shows the last import result with:

• imported row count
• import mode
• batch ID
• created payees
• created aliases

You can choose View All Transactions to review the imported rows in the transactions table.

Deleting an import batch #

Historical imports are tracked as batches.

Use Delete Batch or Delete Imported Batch when you need to remove an import.

Deleting a reporting-only batch removes the reporting-only historical rows. Deleting a full ledger batch removes the live transactions that were created by that batch, so review carefully before using it.

Important behavior to remember #

• Reporting-only rows are for reporting and transaction review, not balance math.
• Full ledger rows are normal transactions and affect balances.
• Historical imports are CSV-based.
• The app analyzes the file before saving anything.
• A backup is required immediately before import.
• Use external_id when your source system provides a stable transaction ID and you want duplicate detection across imports.