Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

fix sync opening_balance on Pluggy accounts to match provider balance

Tássio Noronhafcaea5a85b65
diff --git a/backend/alembic/versions/029_backfill_opening_balance_for_connected_accounts.py b/backend/alembic/versions/029_backfill_opening_balance_for_connected_accounts.py
new file mode 100644
index 00000000..c14e01ec
--- /dev/null
+++ b/backend/alembic/versions/029_backfill_opening_balance_for_connected_accounts.py
@@ -0,0 +1,144 @@
+"""backfill opening_balance for connected accounts
+
+Revision ID: 029
+Revises: 028
+Create Date: 2026-04-16
+
+Providers only return ~1 year of history but report the true current balance,
+so for every existing Pluggy-linked account the sum of imported transactions
+doesn't equal account.balance. The difference is the account's real balance
+at the start of the import window, which was never recorded anywhere. This
+migration inserts a synthetic `source='opening_balance'` transaction on each
+connected account so that SUM(txs) = account.balance going forward — making
+balance_history and the running-balance column in the UI line up with the
+card balance.
+
+Idempotent: skips accounts that already have an opening_balance transaction.
+"""
+
+import uuid
+from datetime import timedelta
+from decimal import Decimal
+
+from alembic import op
+from sqlalchemy import text
+
+revision = "029"
+down_revision = "028"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+ conn = op.get_bind()
+
+ # Connected accounts that don't already have an opening_balance tx
+ accounts = conn.execute(
+ text(
+ """
+ SELECT a.id, a.user_id, a.balance, a.currency, a.type
+ FROM accounts a
+ WHERE a.connection_id IS NOT NULL
+ AND NOT EXISTS (
+ SELECT 1 FROM transactions t
+ WHERE t.account_id = a.id AND t.source = 'opening_balance'
+ )
+ """
+ )
+ ).fetchall()
+
+ for acc in accounts:
+ acc_id, user_id, balance, currency, acc_type = acc
+ is_cc = acc_type == "credit_card"
+ # CC balance is stored as positive debt and displayed negated, so the
+ # target that SUM(signed txs) must hit is -balance. Other accounts
+ # target the stored balance directly.
+ target = (-Decimal(balance)) if is_cc else Decimal(balance)
+
+ row = conn.execute(
+ text(
+ """
+ SELECT
+ COALESCE(SUM(
+ CASE
+ WHEN t.type = 'credit' THEN
+ CASE
+ WHEN t.currency = :acc_currency THEN t.amount
+ ELSE COALESCE(t.amount_primary, t.amount)
+ END
+ ELSE
+ -CASE
+ WHEN t.currency = :acc_currency THEN t.amount
+ ELSE COALESCE(t.amount_primary, t.amount)
+ END
+ END
+ ), 0) AS tx_sum,
+ MIN(t.date) AS oldest_date
+ FROM transactions t
+ WHERE t.account_id = :acc_id
+ AND t.source <> 'opening_balance'
+ """
+ ),
+ {"acc_id": acc_id, "acc_currency": currency},
+ ).fetchone()
+
+ tx_sum = Decimal(str(row[0] or 0))
+ oldest_date = row[1]
+ offset = (target - tx_sum).quantize(Decimal("0.01"))
+
+ # Sub-cent offsets are rounding noise; no backfill needed.
+ if abs(offset) < Decimal("0.01"):
+ continue
+
+ opening_type = "credit" if offset > 0 else "debit"
+ amount = abs(offset)
+ opening_date = (oldest_date - timedelta(days=1)) if oldest_date else None
+
+ if opening_date is None:
+ # No transactions yet — skip; first sync will create the opening tx.
+ continue
+
+ conn.execute(
+ text(
+ """
+ INSERT INTO transactions (
+ id, user_id, account_id, description, amount, currency,
+ date, effective_date, type, source, status, created_at
+ ) VALUES (
+ :id, :user_id, :account_id, :description, :amount, :currency,
+ :date, :effective_date, :type, 'opening_balance', 'posted', NOW()
+ )
+ """
+ ),
+ {
+ "id": str(uuid.uuid4()),
+ "user_id": str(user_id),
+ "account_id": str(acc_id),
+ "description": "Saldo inicial",
+ "amount": amount,
+ "currency": currency,
+ "date": opening_date,
+ "effective_date": opening_date,
+ "type": opening_type,
+ },
+ )
+
+
+def downgrade() -> None:
+ # Reverse: drop every synthetic opening_balance on connected accounts that
+ # this migration could have created. Can't distinguish rows created here
+ # from ones created later by the sync service, so we match on description
+ # + source + connected-ness, which is the signature this migration writes.
+ conn = op.get_bind()
+ conn.execute(
+ text(
+ """
+ DELETE FROM transactions
+ WHERE source = 'opening_balance'
+ AND description = 'Saldo inicial'
+ AND account_id IN (
+ SELECT id FROM accounts WHERE connection_id IS NOT NULL
+ )
+ """
+ )
+ )
diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.py
index 3f027c15..38e9b5d9 100644
--- a/backend/app/services/account_service.py
+++ b/backend/app/services/account_service.py
@@ -290,6 +290,101 @@ async def _recompute_effective_dates(session: AsyncSession, account: Account) ->
apply_effective_date(tx, account)
+async def sync_opening_balance_for_connected_account(
+ session: AsyncSession, account: Account
+) -> None:
+ """Reconcile the opening_balance transaction so SUM(all txs) = account.balance.
+
+ Providers (Pluggy etc.) typically only return ~1 year of history, so the sum
+ of imported transactions rarely equals the account's true current balance.
+ This helper computes the missing opening balance and upserts a synthetic
+ `source='opening_balance'` transaction that closes the gap. After this runs,
+ balance_history and running-balance walks line up with the card balance.
+
+ Call after adding new transactions in a sync (initial or incremental).
+ Does not commit; the caller is responsible for the transaction boundary.
+ """
+ if account.connection_id is None:
+ return
+
+ # For connected CC accounts the stored balance is positive debt and the UI
+ # displays it negated (account_service.serialize_account). The sum of signed
+ # transaction amounts on a CC trends negative as debt accrues, so the target
+ # we want SUM(signed txs) to hit is -balance. For every other account type
+ # the target is simply the stored balance.
+ is_cc = account.type == "credit_card"
+ target = -account.balance if is_cc else account.balance
+
+ effective_amount = case(
+ (Transaction.currency == account.currency, Transaction.amount),
+ else_=func.coalesce(Transaction.amount_primary, Transaction.amount),
+ )
+ signed_amount = case(
+ (Transaction.type == "credit", effective_amount),
+ else_=-effective_amount,
+ )
+
+ sum_result = await session.execute(
+ select(func.coalesce(func.sum(signed_amount), 0)).where(
+ Transaction.account_id == account.id,
+ Transaction.source != "opening_balance",
+ )
+ )
+ tx_sum = Decimal(str(sum_result.scalar() or 0))
+
+ offset = Decimal(str(target)) - tx_sum
+
+ existing = await session.execute(
+ select(Transaction).where(
+ Transaction.account_id == account.id,
+ Transaction.source == "opening_balance",
+ )
+ )
+ existing_tx = existing.scalar_one_or_none()
+
+ # Offsets below one cent are rounding noise; drop any stale opening tx.
+ if abs(offset) < Decimal("0.01"):
+ if existing_tx:
+ await session.delete(existing_tx)
+ return
+
+ oldest_result = await session.execute(
+ select(func.min(Transaction.date)).where(
+ Transaction.account_id == account.id,
+ Transaction.source != "opening_balance",
+ )
+ )
+ oldest_date = oldest_result.scalar()
+ opening_date = (oldest_date - timedelta(days=1)) if oldest_date else _Date.today()
+
+ # Sign convention matches the rest of the codebase: credit = +, debit = -
+ # regardless of account type. A positive offset needs a credit to raise the
+ # running sum to target; a negative offset needs a debit.
+ opening_type = "credit" if offset > 0 else "debit"
+ amount = abs(offset).quantize(Decimal("0.01"))
+
+ if existing_tx:
+ existing_tx.amount = amount
+ existing_tx.type = opening_type
+ existing_tx.date = opening_date
+ existing_tx.currency = account.currency
+ apply_effective_date(existing_tx, account)
+ else:
+ opening_tx = Transaction(
+ user_id=account.user_id,
+ account_id=account.id,
+ description="Saldo inicial",
+ amount=amount,
+ currency=account.currency,
+ date=opening_date,
+ type=opening_type,
+ source="opening_balance",
+ )
+ apply_effective_date(opening_tx, account)
+ session.add(opening_tx)
+ await session.flush()
+
+
async def delete_account(session: AsyncSession, account_id: uuid.UUID, user_id: uuid.UUID) -> bool:
account = await get_account(session, account_id, user_id)
if not account:
diff --git a/backend/app/services/connection_service.py b/backend/app/services/connection_service.py
index 39185df5..5c2d0f29 100644
--- a/backend/app/services/connection_service.py
+++ b/backend/app/services/connection_service.py
@@ -13,6 +13,7 @@ from app.models.category import Category
from app.models.transaction import Transaction
from app.models.user import User
from app.providers import get_provider
+from app.services.account_service import sync_opening_balance_for_connected_account
from app.services.credit_card_service import apply_effective_date
from app.services.rule_service import apply_rules_to_transaction
from app.services.transfer_detection_service import detect_transfer_pairs
@@ -215,6 +216,12 @@ async def handle_oauth_callback(
else:
await stamp_primary_amount(session, user_id, transaction)
+ # After importing the initial batch, reconcile the opening balance so
+ # that SUM(all transactions) matches the provider-reported balance. Any
+ # history that falls outside the provider's lookback window gets
+ # absorbed into this synthetic transaction.
+ await sync_opening_balance_for_connected_account(session, account)
+
# Detect transfer pairs among newly synced transactions
await detect_transfer_pairs(session, user_id, candidate_ids=new_tx_ids)
@@ -499,6 +506,10 @@ async def sync_connection(
else:
await stamp_primary_amount(session, user_id, transaction)
+ # Reconcile the opening balance after any new transactions land so
+ # SUM(all txs) keeps matching account.balance from the provider.
+ await sync_opening_balance_for_connected_account(session, account)
+
# Detect transfer pairs among newly synced transactions
if new_tx_ids:
await detect_transfer_pairs(session, user_id, candidate_ids=new_tx_ids)
diff --git a/backend/tests/test_connection_service.py b/backend/tests/test_connection_service.py
index 2351594f..e39272b8 100644
--- a/backend/tests/test_connection_service.py
+++ b/backend/tests/test_connection_service.py
@@ -512,7 +512,10 @@ async def test_oauth_callback_persists_installment_metadata(
await handle_oauth_callback(session, test_user.id, "code", "pluggy")
rows = (await session.execute(
- select(Transaction).where(Transaction.user_id == test_user.id)
+ select(Transaction).where(
+ Transaction.user_id == test_user.id,
+ Transaction.source != "opening_balance",
+ )
.order_by(Transaction.external_id)
)).scalars().all()
assert len(rows) == 2