Skip to content

fix(dividends): restore the 0588 credit for Trade Republic foreign dividends - #432

Merged
GeiserX merged 3 commits into
mainfrom
fix/tr-dividend-withholding-0588
Nov 16, 2026
Merged

GeiserX merged 3 commits into
mainfrom
fix/tr-dividend-withholding-0588

Conversation

@GeiserX

@GeiserX GeiserX commented Nov 16, 2026 •

Copy link
Copy Markdown
Owner

Problem

Trade Republic credits foreign dividends in EUR. Its export keeps the dividend in USD and the withholding in EUR. Two things went wrong:

  • Casilla 0588 came out 0 for every Trade Republic foreign dividend. The withholding was matched to its dividend by ISIN and currency, so a USD dividend never found its EUR withholding. Users lost the double-taxation credit (about 15% on each US dividend) with no warning.
  • Each foreign dividend opened a USD lot in the FX FIFO that nothing ever closed. The taxpayer never held those dollars. With a Trade Republic file alone this reached no box. Merged with a broker that really holds USD (IBKR), a real conversion there used the Trade Republic "dollars" first and the FX result came out wrong.

The DGT values a dividend at the official rate of the day it is payable (V1024-11) and defers the currency result only «cuando lo recibido sean divisas» (V2466-08, V2422-20). When the broker credits euros, there is no currency to track.

Fix

  • dividends.ts: a withholding first pairs with a same-currency dividend, exactly as before, so IBKR, Degiro and the rest are unchanged. A dividend still unpaired then takes a withholding of the same ISIN in another currency. The withholding is valued in its own currency: EUR is 1:1, never multiplied by the USD rate.
  • New CashTransaction.brokerConvertedToBase flag. The Trade Republic parser sets it on dividends it credited in EUR, and extractCashFxEvents skips those rows. Casilla 0029 is unchanged: gross USD × ECB rate of the payment date.
  • A Hard Trace entry in CLAUDE.md.

On a Trade Republic export with two $10 US dividends: 0588 goes from 0.00 to 2.63, 0029 stays 17.82, and the FX trace is empty. Merged with an IBKR file, the FX result now equals IBKR alone.

Tests

13 new tests: engine, parser, and an end-to-end merge with a real IBKR Flex XML. Nine of them fail on the old code. The other four guard existing behaviour, and each one fails against a deliberately wrong version of the fix. Full suite: 2639 passed. Lint and typecheck are clean.

Follow-up, not in this PR: Degiro AutoFX and Trading 212 EUR accounts have the same lot problem.

Refs #96

Summary by CodeRabbit

  • Bug Fixes
    • Foreign-currency dividends with withholding reported in another currency are now matched and valued using the withholding currency and date when a matching security identifier is available.
    • Broker-converted dividends no longer create separate FX lots, while their withholding deductions remain reflected in reporting.

…cy (#96)

Trade Republic keeps a US dividend in USD but books its withholding in EUR.
The matcher required the same ISIN and currency, so the pair never matched
and Casilla 0588 came out 0 for every TR foreign dividend.

A second pass now pairs a still-unmatched dividend with a withholding of the
same ISIN in another currency, after the unchanged same-currency pass, so
every broker that matched before pairs exactly as before. The withholding is
valued in its own currency (EUR 1:1), never at the dividend's rate.
TR converts a foreign dividend and credits EUR, so the taxpayer never holds
the USD. Each dividend still opened a USD lot that nothing closed: harmless
alone, but merged with an IBKR file FIFO consumed those dollars first and
moved 1633/1637.

The TR parser flags such dividends with CashTransaction.brokerConvertedToBase
and extractCashFxEvents skips flagged rows. 0029 is unchanged (gross USD at
the ECB rate of the payment date).
@coderabbitai

coderabbitai Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The Trade Republic parser now marks foreign-currency dividends credited in the account currency. FX event extraction skips marked transactions. Added tests cover cross-currency withholding matches and end-to-end dividend reporting.

Changes: Foreign Dividend Currency Handling

Layer / File(s) Summary
Mark converted dividends and skip FX events
src/types/ibkr.ts, src/parsers/trade-republic.ts, src/engine/fx-fifo.ts, CLAUDE.md
CashTransaction adds an optional brokerConvertedToBase flag. The Trade Republic parser sets it when the original dividend currency differs from the account currency. FX event extraction skips marked transactions. CLAUDE.md documents the matching and FX-lot handling.
Validate withholding matching and reporting
tests/parsers/trade-republic.test.ts, tests/engine/dividends.test.ts, tests/integration/tr-foreign-dividend-e2e.test.ts
Tests cover cross-currency withholding valuation, same-currency match precedence, missing ISIN and exchange-rate cases, parser flags, and end-to-end dividend reporting with and without FX processing.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Merge Risk: Minimal · up to 4ea1e

The change restores the box 0588 credit for Trade Republic foreign dividends and keeps these dividends out of FX lots. No merge-blocking risk is evident from the supplied context.

Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names the main change: restoring the 0588 credit for Trade Republic foreign dividends. The raw summary and PR objectives confirm the change adds cross-currency withholding matching for USD d…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: restoring the 0588 credit for Trade Republic foreign dividends. The raw summary and PR objectives confirm the change adds cross-currency withholding matching for USD dividends with EUR withholding, a brokerConvertedToBase flag, and FX-event skipping. The title is specific and matches the changeset. It is 76 characters, within a typical length, and follows conventional commit style.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between 2cf2411 and 4ea1e37.

Files selected for processing: 8

  • CLAUDE.md
  • src/engine/dividends.ts
  • src/engine/fx-fifo.ts
  • src/parsers/trade-republic.ts
  • src/types/ibkr.ts
  • tests/engine/dividends.test.ts
  • tests/integration/tr-foreign-dividend-e2e.test.ts
  • tests/parsers/trade-republic.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.08%. Comparing base (2a98f4a) to head (4ea1e37).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@            Coverage Diff             @@
##             main     #432      +/-   ##
==========================================
+ Coverage   93.07%   93.08%   +0.01%     
==========================================
  Files          63       63              
  Lines        6840     6856      +16     
  Branches     2337     2343       +6     
==========================================
+ Hits         6366     6382      +16     
  Misses        391      391              
  Partials       83       83              
Files with missing lines Coverage Δ
src/engine/dividends.ts 100.00% <ø> (ø)
src/engine/fx-fifo.ts 99.55% <100.00%> (+<0.01%) ⬆️
src/parsers/trade-republic.ts 94.70% <100.00%> (+0.07%) ⬆️
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@GeiserX
GeiserX merged commit 5375f97 into main Nov 16, 2026
12 of 16 checks passed
@GeiserX
GeiserX deleted the fix/tr-dividend-withholding-0588 branch November 16, 2026 14:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant