Skip to content

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

fix(accounts): net intermediate card payments into the bill total (#1267)

Tássio Noronha446351bd0c32
diff --git a/backend/app/services/_query_filters.py b/backend/app/services/_query_filters.py
index 707b38fb..891fe3f5 100644
--- a/backend/app/services/_query_filters.py
+++ b/backend/app/services/_query_filters.py
@@ -177,21 +177,27 @@ def counts_as_pnl():
)
-def counts_on_bill():
+def counts_on_bill(net_payments: bool = False):
"""SQL filter: True when a transaction belongs on a credit-card bill.
A bill total is an *amount owed*, not a reporting figure, and the two
answer to different authorities: the bill has to match what the bank
says you owe, while P/L answers to how the user chose to categorize
their spending. So the card's cycle total cannot reuse
- `counts_as_pnl` — every judgment that helper makes about what counts
+ `counts_as_pnl`. Every judgment that helper makes about what counts
as *spending* is a judgment the bank never made.
Kept out, because they are genuinely not charges on this bill:
- - paired transfers (the bill *payment* is not a purchase),
+ - paired transfers, by default (the bill *payment* is not a
+ purchase). With ``net_payments=True`` the *credit* leg of a
+ paired transfer counts instead: an intermediate payment into the
+ card shrinks the amount owed, the way a refund does. Callers
+ net only what is left after the payment settles any debt that
+ was already outstanding (banks apply repayments oldest first),
+ see `get_account_summary`.
- settlement debits (a repayment of a share already booked),
- rows the user flagged `is_ignored`, on the transaction or its
- category — those leave the account balance too, so dropping them
+ category. Those leave the account balance too, so dropping them
from the bill keeps the card's two numbers telling one story.
`treat_as_transfer` categories are handled asymmetrically, and this is
@@ -226,12 +232,37 @@ def counts_on_bill():
transfer_category = Transaction.category_id.in_(
select(Category.id).where(Category.treat_as_transfer.is_(True))
)
+ if net_payments:
+ # The credit leg of a paired transfer is a payment by
+ # construction: the pair proves the money moved between the
+ # user's own accounts, so the pair itself and a transfer-like
+ # category tag on it cannot keep it off the bill.
+ paired_payment = and_(
+ Transaction.type == "credit",
+ Transaction.transfer_pair_id.is_not(None),
+ )
+ transfer_clause = or_(
+ Transaction.transfer_pair_id.is_(None), paired_payment,
+ )
+ category_clause = or_(
+ Transaction.type == "debit",
+ Transaction.category_id.is_(None),
+ ~transfer_category,
+ paired_payment,
+ )
+ else:
+ transfer_clause = Transaction.transfer_pair_id.is_(None)
+ category_clause = or_(
+ Transaction.type == "debit",
+ Transaction.category_id.is_(None),
+ ~transfer_category,
+ )
return and_(
- Transaction.transfer_pair_id.is_(None),
+ transfer_clause,
Transaction.is_ignored.is_(False),
~and_(Transaction.source == "settlement", Transaction.type == "debit"),
or_(Transaction.category_id.is_(None), ~ignored_category),
- or_(Transaction.type == "debit", Transaction.category_id.is_(None), ~transfer_category),
+ category_clause,
)
diff --git a/backend/app/services/account_service.py b/backend/app/services/account_service.py
index 59737902..e12f4cc4 100644
--- a/backend/app/services/account_service.py
+++ b/backend/app/services/account_service.py
@@ -1009,6 +1009,69 @@ async def get_account_summary(
counts_on_bill() if account.type == "credit_card" else counts_as_pnl()
)
+ # Intermediate payments into the card (the credit leg of a paired
+ # transfer) reduce the bill total, but only by what is left after
+ # they settle the debt that was already outstanding when the window
+ # opened. Banks apply repayments oldest first: paying last cycle's
+ # bill inside this window must not read as this cycle's charges
+ # disappearing, while anything paid beyond that older debt can only
+ # settle this cycle's charges, so the bank bills the net (issue #668).
+ prior_debt = 0.0
+ paid_now = 0.0
+ paid_later = 0.0
+ if account.type == "credit_card":
+ prior_result = await session.execute(
+ select(func.coalesce(func.sum(
+ case(
+ (Transaction.type == "credit", effective_amount),
+ else_=-effective_amount,
+ )
+ ), 0)).where(
+ Transaction.account_id == account_id,
+ bucket_date < date_from,
+ # Rows linked to the selected bill belong to it whatever
+ # their date (see `_scope`), so they are not older debt.
+ *([] if bill_id is None else [or_(
+ Transaction.bill_id.is_(None), Transaction.bill_id != bill_id,
+ )]),
+ Transaction.is_ignored == False,
+ or_(
+ Transaction.category_id.is_(None),
+ Transaction.category_id.not_in(
+ select(Category.id).where(Category.is_ignored == True)
+ ),
+ ),
+ )
+ )
+ prior_debt = max(0.0, -float(prior_result.scalar() or 0))
+ paired_payment = and_(
+ counts_on_bill(net_payments=True),
+ Transaction.type == "credit",
+ Transaction.transfer_pair_id.is_not(None),
+ Transaction.source != "opening_balance",
+ )
+ paid_now_result = await session.execute(
+ _scope(select(func.coalesce(func.sum(func.abs(effective_amount)), 0)).where(
+ Transaction.account_id == account_id,
+ bucket_date <= today,
+ Transaction.status == "posted",
+ paired_payment,
+ ))
+ )
+ paid_now = float(paid_now_result.scalar() or 0)
+ paid_later_result = await session.execute(
+ _scope(select(func.coalesce(func.sum(func.abs(effective_amount)), 0)).where(
+ Transaction.account_id == account_id,
+ or_(Transaction.status == "pending", bucket_date > today),
+ paired_payment,
+ ))
+ )
+ paid_later = float(paid_later_result.scalar() or 0)
+ # What the posted payments leave over after the older debt, and what
+ # the pending/future ones add on top of that.
+ netted_now = max(0.0, paid_now - prior_debt)
+ netted_total = max(0.0, paid_now + paid_later - prior_debt)
+
# Income = SUM of credit transactions in window (excluding opening_balance
# and paired transfers).
income_result = await session.execute(
@@ -1025,11 +1088,12 @@ async def get_account_summary(
# Expenses = SUM of debit transactions in window (same exclusions).
# For credit-card accounts, NET refund credits against debits so the
- # cycle's "Total da fatura" matches the bank's bill (refunds reduce the
- # invoice amount). Paired transfers are dropped by `transfer_pair_id`;
- # unpaired card payments are dropped by the credit-side `treat_as_transfer`
- # exclusion in `counts_on_bill` (see its docstring for why that's
- # asymmetric with the debit side).
+ # cycle's "Total da fatura" matches the bank's bill (refunds reduce
+ # the invoice amount). Paired transfers are dropped by `transfer_pair_id`
+ # and netted separately below (see `netted_now`); unpaired card payments
+ # are dropped by the credit-side `treat_as_transfer` exclusion in
+ # `counts_on_bill` (see its docstring for why that's asymmetric with the
+ # debit side).
if account.type == "credit_card":
signed_for_bill = case(
(Transaction.type == "credit", -func.abs(effective_amount)),
@@ -1054,7 +1118,7 @@ async def get_account_summary(
summary_filter,
))
)
- monthly_expenses = float(expenses_result.scalar())
+ monthly_expenses = float(expenses_result.scalar()) - netted_now
# Forecast values use the same cycle/date scope as the actual totals, but
# include every pending row and every row bucketed after today. The current
@@ -1094,7 +1158,9 @@ async def get_account_summary(
summary_filter,
))
)
- forecast_expenses = float(forecast_expense_result.scalar() or 0)
+ forecast_expenses = float(forecast_expense_result.scalar() or 0) - (
+ netted_total - netted_now
+ )
opening_balance = (
await get_period_opening_balance(session, account, date_from)
diff --git a/backend/tests/test_account_service.py b/backend/tests/test_account_service.py
index 7d307e2a..7de82a94 100644
--- a/backend/tests/test_account_service.py
+++ b/backend/tests/test_account_service.py
@@ -922,6 +922,160 @@ async def test_get_account_summary_bill_unpaired_payment_credit_still_nets_out(
assert summary["monthly_expenses"] == pytest.approx(100.0)
+async def test_get_account_summary_bill_nets_paired_payment_when_cycle_starts_flat(
+ session: AsyncSession, test_user, test_workspace
+):
+ """An intermediate payment into the card (the credit leg of a paired
+ transfer) nets against the bill total when the window started with no
+ prior debt: nothing older exists for the payment to settle, so the
+ bank bills the net (issue #668)."""
+ account = await _make_account(session, test_user.id, "CC Mid Pay", acc_type="credit_card")
+ today = date.today()
+ pair_id = uuid.uuid4()
+
+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)
+ await _add_txn(session, test_user.id, account.id, 100, "credit", today)
+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,
+ transfer_pair_id=pair_id)
+
+ summary = await get_account_summary(session, account.id, test_workspace.id)
+ assert summary is not None
+ # 1000 (charge) - 100 (refund) - 400 (intermediate payment) = 500
+ assert summary["monthly_expenses"] == pytest.approx(500.0)
+ # the payment is not income; the refund still is
+ assert summary["monthly_income"] == pytest.approx(100.0)
+
+
+async def test_get_account_summary_bill_nets_only_payment_beyond_prior_debt(
+ session: AsyncSession, test_user, test_workspace
+):
+ """With last cycle's bill still open when the window starts, a payment
+ first settles that older debt; only the excess nets this cycle's bill
+ total (issue #668)."""
+ account = await _make_account(session, test_user.id, "CC Mid Pay Prior", acc_type="credit_card")
+ today = date.today()
+ last_month = today.replace(day=1) - timedelta(days=1)
+
+ await _add_txn(session, test_user.id, account.id, 800, "debit", last_month)
+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)
+ # 800 pays last cycle's bill, 400 is the intermediate payment.
+ await _add_txn(session, test_user.id, account.id, 800, "credit", today,
+ transfer_pair_id=uuid.uuid4())
+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,
+ transfer_pair_id=uuid.uuid4())
+
+ summary = await get_account_summary(session, account.id, test_workspace.id)
+ assert summary is not None
+ assert summary["monthly_expenses"] == pytest.approx(600.0)
+ assert summary["projected_expenses"] == pytest.approx(600.0)
+ assert summary["monthly_income"] == pytest.approx(0.0)
+
+
+async def test_get_account_summary_bill_payment_of_prior_debt_leaves_cycle_total(
+ session: AsyncSession, test_user, test_workspace
+):
+ """Paying only last cycle's bill inside this window does not reduce
+ this cycle's bill total (issue #668)."""
+ account = await _make_account(session, test_user.id, "CC Prior Only", acc_type="credit_card")
+ today = date.today()
+ last_month = today.replace(day=1) - timedelta(days=1)
+
+ await _add_txn(session, test_user.id, account.id, 800, "debit", last_month)
+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)
+ await _add_txn(session, test_user.id, account.id, 800, "credit", today,
+ transfer_pair_id=uuid.uuid4())
+
+ summary = await get_account_summary(session, account.id, test_workspace.id)
+ assert summary is not None
+ assert summary["monthly_expenses"] == pytest.approx(1000.0)
+ assert summary["projected_expenses"] == pytest.approx(1000.0)
+
+
+async def test_get_account_summary_bill_linked_pre_window_payment_is_not_prior_debt(
+ session: AsyncSession, test_user, test_workspace
+):
+ """With a synced bill selected, a paired payment linked to that bill
+ but dated before the window already counts as paid on the bill, so it
+ must not also cancel the older debt: 100 prior debt and a 100 linked
+ payment leave nothing to net against this cycle (issue #668)."""
+ from datetime import datetime, timezone
+ from app.models.credit_card_bill import CreditCardBill
+
+ account = await _make_account(session, test_user.id, "CC Linked Pay", acc_type="credit_card")
+ today = date.today()
+ last_month = today.replace(day=1) - timedelta(days=1)
+ bill = CreditCardBill(
+ user_id=test_user.id, account_id=account.id, external_id="bill-668",
+ due_date=today + timedelta(days=10), total_amount=Decimal("1000"),
+ currency="BRL", created_at=datetime.now(timezone.utc),
+ updated_at=datetime.now(timezone.utc),
+ )
+ session.add(bill)
+ await session.commit()
+
+ await _add_txn(session, test_user.id, account.id, 100, "debit", last_month)
+ payment = await _add_txn(session, test_user.id, account.id, 100, "credit", last_month,
+ transfer_pair_id=uuid.uuid4())
+ charge = await _add_txn(session, test_user.id, account.id, 1000, "debit", today)
+ payment.bill_id = bill.id
+ charge.bill_id = bill.id
+ await session.commit()
+
+ summary = await get_account_summary(
+ session, account.id, test_workspace.id, bill_id=bill.id,
+ )
+ assert summary is not None
+ assert summary["monthly_expenses"] == pytest.approx(1000.0)
+ assert summary["projected_expenses"] == pytest.approx(1000.0)
+
+
+async def test_get_account_summary_bill_nets_paired_payment_with_transfer_category(
+ session: AsyncSession, test_user, test_workspace
+):
+ """A paired payment filed under a transfer-like category still nets
+ the bill total: the transfer pair already proves it is a payment, so
+ the category tag cannot flip it back into 'not a payment'
+ (issue #668)."""
+ account = await _make_account(session, test_user.id, "CC Mid Pay Cat", acc_type="credit_card")
+ today = date.today()
+ pair_id = uuid.uuid4()
+ transfer_cat = await _make_category(session, test_user.id, treat_as_transfer=True)
+
+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)
+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,
+ transfer_pair_id=pair_id, category_id=transfer_cat.id)
+
+ summary = await get_account_summary(session, account.id, test_workspace.id)
+ assert summary is not None
+ assert summary["monthly_expenses"] == pytest.approx(600.0)
+
+
+async def test_get_account_summary_bill_nets_pending_paired_payment_in_projection(
+ session: AsyncSession, test_user, test_workspace
+):
+ """A payment the user marked pending still nets the projected bill
+ total: the projection is the final-bill estimate, and a scheduled
+ payment is part of it (issue #668)."""
+ account = await _make_account(session, test_user.id, "CC Mid Pay Pending", acc_type="credit_card")
+ today = date.today()
+ pair_id = uuid.uuid4()
+
+ await _add_txn(session, test_user.id, account.id, 1000, "debit", today)
+ await _add_txn(session, test_user.id, account.id, 400, "credit", today,
+ transfer_pair_id=pair_id, status="pending")
+
+ summary = await get_account_summary(session, account.id, test_workspace.id)
+ assert summary is not None
+ assert summary["monthly_expenses"] == pytest.approx(1000.0)
+ assert summary["projected_expenses"] == pytest.approx(600.0)
+
+
@pytest.mark.asyncio
async def test_get_account_summary_bill_excludes_ignored_category_charge(
session: AsyncSession, test_user, test_workspace