Skip to content

Connect Your Bank

The Data page is the user-owned ingestion and export workspace. It brings together SimpleFIN, CSV transactions, XLSX bill history, SQLite user exports, matching, demo records, and import history.

This page explains how to connect a bank through SimpleFIN, how transactions flow into BillTracker, how matches are scored, and how to review and undo auto-matches. It is the reference for the entire Data → Bank Sync surface.

What's on the Data page?

The current page presents sections in this order:

  1. Bank Sync
  2. Import Transaction CSV
  3. Transactions
  4. Import Spreadsheet History
  5. Import My Data Export
  6. Demo Data
  7. Download My Data
  8. Import History

This layout moves from incoming records to review, recovery, and export.

How do I connect SimpleFIN?

SimpleFIN is optional and must first be enabled by an administrator.

Connect

  1. Obtain a SimpleFIN Bridge setup token.
  2. Open Data > Bank Sync.
  3. Paste the setup token.
  4. Submit the connection.
  5. Review discovered accounts.
  6. Disable monitoring for accounts that should not participate in matching.

BillTracker claims the one-time token, stores an encrypted access URL, and performs an initial seed sync.

Sync Windows

Action Lookback
Initial connection 44 days (one day under SimpleFIN Bridge's 45-day hard limit)
Manual Sync Now 30 days
Background sync 30 days
Backfill 44 days

The lookback window is sourced from bankSyncConfigService and reflected in the Data page button label, the admin config card, and the toast copy. There is no separate 90-day constant.

Auto-Sync

The worker:

  • Uses the administrator's configured interval, defaulting to 4 hours
  • Skips sources synced less than 1 hour ago
  • Processes sources from oldest sync timestamp to newest
  • Waits 3 seconds between sources
  • Stores source errors without stopping other connections
  • Retries transient failures with up to 3 attempts and 1 s / 2 s delays
  • Times out at 30 seconds per request
  • Applies merchant rules, match suggestions, and spending-category rules after sync

The Data → Bank Sync section is rate-limited to 10 requests per 15 minutes per authenticated user for POST /:id/sync, POST /sync-all, and POST /:id/backfill.

How do I review auto-matched payments?

A collapsible Auto-matched — review panel appears on the Data → Bank Sync section when there are reviewable provider_sync auto-matches in the last 7 days. Each entry shows the payee, date, amount, and the bill it was matched to. An Undo button calls POST /api/payments/:id/undo-auto, which soft-deletes the payment, restores the bill balance (including any interest), and reverts the transaction to unmatched. The panel disappears when the list is empty and refreshes automatically after each Sync Now or Backfill.

What can I do in the Transactions workbench?

Imported and manually created transactions appear in the Transactions section.

State Meaning
Unmatched No bill association exists yet
Matched Connected to a bill and represented in payment history
Ignored Intentionally excluded from bill matching

Available actions include match, unmatch, ignore, unignore, edit, and delete. Clicking Unmatch on a linked transaction in the Bill modal opens a two-option choice dialog:

  • Unmatch this payment only removes only that transaction through a single AlertDialog confirmation.
  • Review all similar matches fetches all linked transactions for the bill whose payee normalizes to the same prefix and opens a checklist dialog where each similar match is pre-checked. Users can deselect individual transactions to keep them matched, use All/None quick-selects, and optionally check a Remove merchant rule checkbox (shown only when a merchant rule matching the payee pattern exists on the bill). The new POST /api/transactions/unmatch-bulk endpoint handles mixed provider_sync and transaction_match entries in a single database transaction.

How does the match-suggestion engine work?

Suggestions score a transaction against user-owned bills by:

  • Amount similarity
  • Date proximity to the due day
  • Name and merchant similarity (word-boundary regex matching)
  • Prior match history
  • Whether the bill already has a payment in the relevant cycle

Users can confirm a suggestion or reject it. Rejections are persisted so the same suggestion is not repeatedly presented. Rejected suggestions resurface after 90 days, and old rejection rows are pruned by the daily cleanup worker.

What are merchant rules?

When a transaction is matched to a bill, BillTracker can store a merchant-to-bill rule. Future synced transactions matching that merchant name are automatically matched and a payment is created without manual review.

Adding A Rule

When you confirm a transaction match, the Create Rule option saves the merchant name and links it to that bill. Rules can also be added directly from the bill editor under Bank Matching Rules. Auto-learning is gated by learnableMerchantFromTransaction(), which rejects payee text that is too short (< 4 chars) or composed entirely of generic financial tokens (ach, atm, transfer, fee, etc.) — preventing a rule like "ACH Payment" from becoming a catch-all. Background auto-matching (via applyMerchantRules) never creates rules; only explicit user actions do.

Word-Boundary Matching

Merchant rules use word-boundary regex matching rather than simple substring checks. A rule for "Suno" matches "Suno inc" and "Suno AI" but does not match "Sunoco" — preventing false positives from substring collisions. Merchant rules are also sorted by length descending before matching so the longer (more specific) rule always wins when multiple rules could match a transaction.

Ambiguity Protection

applyMerchantRules checks whether the most-specific tier of matching merchant rules maps to more than one distinct bill (e.g., two bills both named "Amazon" with matching rules). When ambiguous, the transaction is skipped and left for manual review rather than silently attributing to the wrong bill.

Auto-Fix Month Crossing

Some bills consistently post to the bank 1-5 days after month end (e.g. AT&T due May 29, posts June 1). Each rule has an Auto-fix toggle in the bill editor's Bank Matching Rules section. When enabled, payments that cross a month boundary are automatically attributed to the last day of the prior month — no popup, no manual intervention.

Historical Payment Import

When a new rule is added, a dialog opens automatically asking how to handle past transactions:

  • Import all N payments — treats every historical match as a payment
  • Choose which ones — checkbox list showing each transaction's date, amount, and current match status
  • Skip — future only — leaves past transactions untouched

Already-imported transactions are shown dimmed at the bottom for context. The backend provides GET /api/bills/:id/merchant-rules/candidates to list matching transactions and POST /api/bills/:id/merchant-rules/import-historical to import a selected list.

Sync Bank Button

The Tracker header shows a Sync Bank button when SimpleFIN is enabled, the user has at least one connected source, and at least one merchant rule exists. Clicking syncs all sources, applies rules, and shows a toast with matched bill names (e.g. "Synced — AT&T · Netflix · Spotify ✓"). Tracker refetches automatically so new payments appear immediately.

Late Attribution

When a bank-synced payment crosses a month boundary (posted in the new month but due in the prior month), a dialog prompts: "AT&T payment of $332.97 posted June 1 — should it count for May?" Accepting moves the paid date to the last day of the prior month. Multiple candidates are queued and shown one at a time. Late attributions from the Sync Bank button and from individual bill syncs are processed in the same queue. The reclassification uses PATCH /api/payments/:id/attribute-to-month, which is specifically allowed for provider_sync payments and never changes the amount or the bank link.

How are bank transactions categorized?

Bank transactions can be categorized separately from bill categories. The /spending page (between Categories and Snowball) shows a month navigator, an overview strip (total spending, uncategorized, income received), a per-category breakdown with budget progress bars and an inline budget editor, and a paginated transaction list with an inline category picker. Selecting a category offers to save a merchant rule, which back-fills all existing unmatched transactions from that merchant and auto-categorizes new ones on every future sync.

A Copy last month button on the spending page copies all spending budget entries from the prior month into the current month in a single POST /api/spending/budgets/copy request.

How do advisory non-bill filters work?

The transaction recommendation layer uses a seeded advisory catalog of more than 5,000 patterns plus bill-like override terms.

Confidence Interface effect
High De-emphasizes bill creation and explains that the transaction is probably not a bill
Medium Mutes the create-bill action
Override term Allows a likely recurring bill to remain actionable

The filter is advisory. A user can still create a bill when the transaction is genuinely recurring.

How do I import a CSV?

CSV import is a two-stage flow:

  1. Upload a bank or card CSV, maximum 10 MB.
  2. Review headers, sample records, and suggested field mappings.
  3. Correct mappings if needed.
  4. Commit normalized transactions.

Committed transactions use a stable hash for duplicate detection and share the same matching workspace as SimpleFIN transactions.

How do I import an XLSX bill history?

Spreadsheet history import is also staged:

  1. Upload an .xlsx workbook, maximum 10 MB.
  2. Select a sheet or parse all sheets.
  3. Review inferred dates, amounts, categories, and possible bill matches.
  4. Choose row-level actions.
  5. Apply only confirmed decisions.

Preview sessions expire after 24 hours. Ambiguous rows remain explicit user decisions rather than silent writes.

How do I restore a SQLite user export?

Use this path to restore a SQLite user export created by BillTracker:

  1. Upload the export, maximum 50 MB.
  2. Review the validated preview and counts.
  3. Apply the import.

Ownership always comes from the signed-in user. This is not a full server database restore.

What can I export?

The Data page provides:

Export Contents
SQLite user export Bills, payments, categories, monthly state, starting amounts, history ranges, notes, metadata
Excel databook The same user-owned data in workbook sheets

Full server backup files remain an admin-only feature.

Next steps