Skip to content

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

feat: add quarterly recurring transactions (#499)

seraphblade2010d5e1a80bb20f
diff --git a/backend/app/models/recurring_transaction.py b/backend/app/models/recurring_transaction.py
index a5ef42ac..becc8276 100644
--- a/backend/app/models/recurring_transaction.py
+++ b/backend/app/models/recurring_transaction.py
@@ -34,7 +34,7 @@ class RecurringTransaction(Base):
amount: Mapped[Decimal] = mapped_column(Numeric(precision=15, scale=2))
currency: Mapped[str] = mapped_column(String(3), default="USD")
type: Mapped[str] = mapped_column(String(10)) # debit, credit
- frequency: Mapped[str] = mapped_column(String(20)) # monthly, weekly, yearly
+ frequency: Mapped[str] = mapped_column(String(20)) # weekly, monthly, quarterly, yearly
day_of_month: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
start_date: Mapped[date] = mapped_column(Date)
end_date: Mapped[Optional[date]] = mapped_column(Date, nullable=True)
diff --git a/backend/app/schemas/recurring_transaction.py b/backend/app/schemas/recurring_transaction.py
index 8fccd313..e020ee33 100644
--- a/backend/app/schemas/recurring_transaction.py
+++ b/backend/app/schemas/recurring_transaction.py
@@ -11,7 +11,7 @@ class RecurringTransactionCreate(BaseModel):
amount: Decimal
currency: str = "USD"
type: str # debit, credit
- frequency: str # monthly, weekly, yearly
+ frequency: str # weekly, monthly, quarterly, yearly
day_of_month: Optional[int] = None
start_date: _Date
end_date: Optional[_Date] = None
@@ -26,7 +26,7 @@ class RecurringTransactionUpdate(BaseModel):
amount: Optional[Decimal] = None
currency: Optional[str] = None
type: Optional[str] = None
- frequency: Optional[str] = None
+ frequency: Optional[str] = None # weekly, monthly, quarterly, yearly
day_of_month: Optional[int] = None
start_date: Optional[_Date] = None
end_date: Optional[_Date] = None
diff --git a/backend/app/services/recurring_transaction_service.py b/backend/app/services/recurring_transaction_service.py
index 389e67c6..e756def7 100644
--- a/backend/app/services/recurring_transaction_service.py
+++ b/backend/app/services/recurring_transaction_service.py
@@ -134,30 +134,40 @@ async def delete_recurring_transaction(
return True
+def _advance_months(current: date, months: int, intended_day: int) -> date:
+ """Advance by calendar months, clamping only in a shorter target month."""
+ month_index = current.month - 1 + months
+ year = current.year + month_index // 12
+ month = month_index % 12 + 1
+ day = min(intended_day, calendar.monthrange(year, month)[1])
+ return date(year, month, day)
+
+
def _advance_date(
current: date, frequency: str, intended_day: Optional[int] = None,
) -> date:
"""Advance a date by the given frequency.
- For monthly/yearly, ``intended_day`` is the day the user actually wants
- (e.g. 31). We cap it to the target month's length so Feb clamps to 28/29,
- but subsequent months recover to 31/30 instead of sticking at 28.
- Falls back to ``current.day`` when not provided."""
+ For monthly, quarterly, and yearly recurrences, ``intended_day`` is the day
+ the user actually wants (e.g. 31). We cap it to the target month's length
+ so short months clamp, but subsequent occurrences recover to the intended
+ day when it exists again. Falls back to ``current.day`` when not provided.
+ """
if frequency == "weekly":
return current + timedelta(weeks=1)
+
target_day = intended_day if intended_day else current.day
+ if frequency == "monthly":
+ return _advance_months(current, 1, target_day)
+ if frequency == "quarterly":
+ return _advance_months(current, 3, target_day)
if frequency == "yearly":
year = current.year + 1
day = min(target_day, calendar.monthrange(year, current.month)[1])
return date(year, current.month, day)
- # monthly (default)
- month = current.month + 1
- year = current.year
- if month > 12:
- month = 1
- year += 1
- day = min(target_day, calendar.monthrange(year, month)[1])
- return date(year, month, day)
+
+ # Preserve the existing monthly fallback for unknown legacy values.
+ return _advance_months(current, 1, target_day)
def get_occurrences_in_range(
diff --git a/backend/mcp_server/tools/proposals.py b/backend/mcp_server/tools/proposals.py
index 1f0d4800..f6c337f1 100644
--- a/backend/mcp_server/tools/proposals.py
+++ b/backend/mcp_server/tools/proposals.py
@@ -533,7 +533,8 @@ async def propose_create_transaction(
description=_PROPOSAL_PREFACE + (
"Build a preview for adding a recurring transaction / subscription "
"(e.g. 'Netflix R$55 every month on the 10th'). Frequency is one "
- "of weekly/monthly/yearly. For monthly use day_of_month (1-31)."
+ "of weekly/monthly/quarterly/yearly. For monthly or quarterly use "
+ "day_of_month (1-31)."
),
parameters={
"type": "object",
@@ -541,8 +542,8 @@ async def propose_create_transaction(
"description": {"type": "string", "minLength": 1, "maxLength": 500},
"amount": {"type": "number", "exclusiveMinimum": 0},
"type": {"type": "string", "enum": ["debit", "credit"]},
- "frequency": {"type": "string", "enum": ["weekly", "monthly", "yearly"]},
- "day_of_month": {"type": "integer", "minimum": 1, "maximum": 31, "description": "Required for monthly"},
+ "frequency": {"type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"]},
+ "day_of_month": {"type": "integer", "minimum": 1, "maximum": 31, "description": "Required for monthly or quarterly"},
"start_date": {"type": "string", "format": "date", "description": "Defaults to today"},
"end_date": {"type": "string", "format": "date"},
"account_id": {"type": "string", "format": "uuid"},
@@ -572,8 +573,8 @@ async def propose_create_recurring_transaction(
currency: str | None = None,
apply: bool = False,
) -> dict[str, Any]:
- if frequency == "monthly" and not day_of_month:
- return {"error": "day_of_month is required for monthly frequency"}
+ if frequency in ("monthly", "quarterly") and not day_of_month:
+ return {"error": "day_of_month is required for monthly or quarterly frequency"}
ws_id = await resolve_workspace_id(session, ctx)
acc = (await session.execute(
select(Account).where(Account.id == parse_uuid(account_id), Account.workspace_id == ws_id)
@@ -648,7 +649,7 @@ async def propose_create_recurring_transaction(
"recurring_id": {"type": "string", "format": "uuid"},
"description": {"type": "string", "minLength": 1, "maxLength": 500},
"amount": {"type": "number", "exclusiveMinimum": 0},
- "frequency": {"type": "string", "enum": ["weekly", "monthly", "yearly"]},
+ "frequency": {"type": "string", "enum": ["weekly", "monthly", "quarterly", "yearly"]},
"day_of_month": {"type": "integer", "minimum": 1, "maximum": 31},
"end_date": {"type": "string", "format": "date"},
"category_id": {"type": "string", "format": "uuid"},
diff --git a/backend/tests/test_recurring_api.py b/backend/tests/test_recurring_api.py
index 32d28146..a1b4b92c 100644
--- a/backend/tests/test_recurring_api.py
+++ b/backend/tests/test_recurring_api.py
@@ -78,6 +78,30 @@ async def test_create_recurring_skip_first_monthly(client, auth_headers, test_ac
assert data["next_occurrence"] == "2026-02-15"
+async def test_create_recurring_skip_first_quarterly(client, auth_headers, test_account):
+ """Quarterly is accepted by the API and skip_first advances three calendar months."""
+ response = await client.post(
+ "/api/recurring-transactions",
+ json={
+ "description": "Insurance",
+ "amount": 300.00,
+ "currency": "BRL",
+ "type": "debit",
+ "frequency": "quarterly",
+ "day_of_month": 31,
+ "start_date": "2026-01-31",
+ "skip_first": True,
+ "account_id": str(test_account.id),
+ },
+ headers=auth_headers,
+ )
+ assert response.status_code == 201
+ data = response.json()
+ assert data["frequency"] == "quarterly"
+ assert data["next_occurrence"] == "2026-04-30"
+
+
@pytest.mark.asyncio
async def test_generate_pending_creates_transactions(client, auth_headers, test_account):
"""Generate pending creates transactions and advances next_occurrence."""
diff --git a/backend/tests/test_recurring_match.py b/backend/tests/test_recurring_match.py
index d62065fd..f39a4c00 100644
--- a/backend/tests/test_recurring_match.py
+++ b/backend/tests/test_recurring_match.py
@@ -197,6 +197,21 @@ async def test_advance_past_moves_pointer(session, test_user, test_workspace, ac
assert bill.next_occurrence == date(2025, 2, 10)
+async def test_advance_past_moves_quarterly_pointer(session, test_user, test_workspace, account):
+ bill = await _make_bill(
+ session,
+ test_workspace,
+ test_user,
+ account,
+ frequency="quarterly",
+ day_of_month=31,
+ start_date=date(2025, 1, 31),
+ )
+ rms.advance_past(bill, date(2025, 1, 31))
+ assert bill.next_occurrence == date(2025, 4, 30)
+
+
@pytest.mark.asyncio
async def test_advance_past_deactivates_past_end_date(session, test_user, test_workspace, account):
bill = await _make_bill(
diff --git a/backend/tests/test_recurring_transaction_service.py b/backend/tests/test_recurring_transaction_service.py
index 7d68b03c..a4463846 100644
--- a/backend/tests/test_recurring_transaction_service.py
+++ b/backend/tests/test_recurring_transaction_service.py
@@ -259,6 +259,29 @@ def test_advance_date_yearly_intended_day_leap_recovery():
assert y4 == date(2028, 2, 29)
+def test_advance_date_quarterly():
+ assert _advance_date(date(2026, 1, 15), "quarterly") == date(2026, 4, 15)
+ assert _advance_date(date(2026, 11, 15), "quarterly") == date(2027, 2, 15)
+
+
+def test_advance_date_quarterly_intended_day_recovers_after_clamping():
+ april = _advance_date(date(2026, 1, 31), "quarterly", intended_day=31)
+ assert april == date(2026, 4, 30)
+ july = _advance_date(april, "quarterly", intended_day=31)
+ assert july == date(2026, 7, 31)
+ october = _advance_date(july, "quarterly", intended_day=31)
+ assert october == date(2026, 10, 31)
+ january = _advance_date(october, "quarterly", intended_day=31)
+ assert january == date(2027, 1, 31)
+
+
+def test_advance_date_quarterly_leap_year_clamping_recovers():
+ february = _advance_date(date(2023, 11, 30), "quarterly", intended_day=30)
+ assert february == date(2024, 2, 29)
+ may = _advance_date(february, "quarterly", intended_day=30)
+ assert may == date(2024, 5, 30)
+
+
# ---------------------------------------------------------------------------
# get_occurrences_in_range
# ---------------------------------------------------------------------------
@@ -367,6 +390,35 @@ def test_get_occurrences_in_range_monthly_day_29_does_not_drift():
]
+def test_get_occurrences_in_range_quarterly():
+ occurrences = get_occurrences_in_range(
+ start=date(2026, 1, 31),
+ frequency="quarterly",
+ end_date=None,
+ range_start=date(2026, 1, 1),
+ range_end=date(2027, 2, 1),
+ intended_day=31,
+ )
+ assert occurrences == [
+ date(2026, 1, 31),
+ date(2026, 4, 30),
+ date(2026, 7, 31),
+ date(2026, 10, 31),
+ date(2027, 1, 31),
+ ]
+
+
+def test_get_occurrences_in_range_quarterly_respects_end_date():
+ occurrences = get_occurrences_in_range(
+ start=date(2026, 1, 15),
+ frequency="quarterly",
+ end_date=date(2026, 7, 1),
+ range_start=date(2026, 1, 1),
+ range_end=date(2027, 1, 1),
+ )
+ assert occurrences == [date(2026, 1, 15), date(2026, 4, 15)]
+
+
# ---------------------------------------------------------------------------
# generate_pending
# ---------------------------------------------------------------------------
@@ -406,6 +458,48 @@ async def test_generate_pending(session: AsyncSession, test_user, test_workspace
assert rec.next_occurrence == date(2025, 4, 1)
+async def test_generate_pending_quarterly_respects_end_date(
+ session: AsyncSession, test_user, test_workspace, test_account_for_recurring
+):
+ rec = await create_recurring_transaction(
+ session,
+ test_workspace.id,
+ test_user.id,
+ RecurringTransactionCreate(
+ description="Quarterly Insurance",
+ amount=Decimal("300"),
+ type="debit",
+ frequency="quarterly",
+ day_of_month=30,
+ start_date=date(2023, 11, 30),
+ end_date=date(2024, 5, 30),
+ account_id=test_account_for_recurring.id,
+ ),
+ )
+
+ count = await generate_pending(session, test_user.id, up_to=date(2024, 12, 31))
+ assert count == 3
+
+ result = await session.execute(
+ select(Transaction)
+ .where(
+ Transaction.recurring_transaction_id == rec.id,
+ Transaction.source == "recurring",
+ )
+ .order_by(Transaction.date)
+ )
+ assert [transaction.date for transaction in result.scalars()] == [
+ date(2023, 11, 30),
+ date(2024, 2, 29),
+ date(2024, 5, 30),
+ ]
+
+ await session.refresh(rec)
+ assert rec.next_occurrence == date(2024, 8, 30)
+ assert rec.is_active is False
+
+
@pytest.mark.asyncio
async def test_generate_pending_deactivates_past_end_date(
session: AsyncSession, test_user, test_workspace, test_account_for_recurring
diff --git a/frontend/src/components/transaction-dialog.tsx b/frontend/src/components/transaction-dialog.tsx
index 2e3d6170..1baae33a 100644
--- a/frontend/src/components/transaction-dialog.tsx
+++ b/frontend/src/components/transaction-dialog.tsx
@@ -378,7 +378,7 @@ function TransactionForm({
!!transaction && (seed?.amount_primary != null || seed?.fx_rate_used != null)
)
const [isRecurring, setIsRecurring] = useState(false)
- const [frequency, setFrequency] = useState<'monthly' | 'weekly' | 'yearly'>('monthly')
+ const [frequency, setFrequency] = useState<RecurringTransaction['frequency']>('monthly')
const [endDate, setEndDate] = useState('')
// Optional split-with-group payload. `null` = leave splits as-is on
// update, or no splits on create. The dedicated section component
@@ -1053,9 +1053,10 @@ function TransactionForm({
<select
className="w-full border border-border rounded-md px-3 py-2 text-sm bg-background focus:outline-none focus-visible:ring-ring/30 focus-visible:ring-[2px]"
value={frequency}
- onChange={(e) => setFrequency(e.target.value as 'monthly' | 'weekly' | 'yearly')}
+ onChange={(e) => setFrequency(e.target.value as RecurringTransaction['frequency'])}
>
<option value="monthly">{t('recurring.monthly')}</option>
+ <option value="quarterly">{t('recurring.quarterly')}</option>
<option value="weekly">{t('recurring.weekly')}</option>
<option value="yearly">{t('recurring.yearly')}</option>
</select>
diff --git a/frontend/src/locales/de.json b/frontend/src/locales/de.json
index fc3a1838..9a9aa9a5 100644
--- a/frontend/src/locales/de.json
+++ b/frontend/src/locales/de.json
@@ -778,6 +778,7 @@
"income": "Einnahme",
"frequency": "Häufigkeit",
"monthly": "Monatlich",
+ "quarterly": "Vierteljährlich",
"weekly": "Wöchentlich",
"yearly": "Jährlich",
"dayOfMonth": "Tag des Monats",
diff --git a/frontend/src/locales/en.json b/frontend/src/locales/en.json
index 5185e48e..77de71d3 100644
--- a/frontend/src/locales/en.json
+++ b/frontend/src/locales/en.json
@@ -778,6 +778,7 @@
"income": "Income",
"frequency": "Frequency",
"monthly": "Monthly",
+ "quarterly": "Quarterly",
"weekly": "Weekly",
"yearly": "Yearly",
"dayOfMonth": "Day of month",
diff --git a/frontend/src/locales/es.json b/frontend/src/locales/es.json
index 210a4336..ce3a20dc 100644
--- a/frontend/src/locales/es.json
+++ b/frontend/src/locales/es.json
@@ -778,6 +778,7 @@
"income": "Ingreso",
"frequency": "Frecuencia",
"monthly": "Mensual",
+ "quarterly": "Trimestral",
"weekly": "Semanal",
"yearly": "Anual",
"dayOfMonth": "Día del mes",
diff --git a/frontend/src/locales/fr.json b/frontend/src/locales/fr.json
index cbecf13a..b6a71a1f 100644
--- a/frontend/src/locales/fr.json
+++ b/frontend/src/locales/fr.json
@@ -778,6 +778,7 @@
"income": "Revenu",
"frequency": "Fréquence",
"monthly": "Mensuelle",
+ "quarterly": "Trimestrielle",
"weekly": "Hebdomadaire",
"yearly": "Annuelle",
"dayOfMonth": "Jour du mois",
diff --git a/frontend/src/locales/it.json b/frontend/src/locales/it.json
index 06eeb736..55792db0 100644
--- a/frontend/src/locales/it.json
+++ b/frontend/src/locales/it.json
@@ -778,6 +778,7 @@
"income": "Entrata",
"frequency": "Frequenza",
"monthly": "Mensile",
+ "quarterly": "Trimestrale",
"weekly": "Settimanale",
"yearly": "Annuale",
"dayOfMonth": "Giorno del mese",
diff --git a/frontend/src/locales/pl.json b/frontend/src/locales/pl.json
index 832407f9..37e8894c 100644
--- a/frontend/src/locales/pl.json
+++ b/frontend/src/locales/pl.json
@@ -820,6 +820,7 @@
"income": "Przychód",
"frequency": "Częstotliwość",
"monthly": "Miesięcznie",
+ "quarterly": "Kwartalnie",
"weekly": "Tygodniowo",
"yearly": "Rocznie",
"dayOfMonth": "Dzień miesiąca",
diff --git a/frontend/src/locales/pt-BR.json b/frontend/src/locales/pt-BR.json
index fc54bf9d..8c3ac00c 100644
--- a/frontend/src/locales/pt-BR.json
+++ b/frontend/src/locales/pt-BR.json
@@ -778,6 +778,7 @@
"income": "Entrada",
"frequency": "Frequência",
"monthly": "Mensal",
+ "quarterly": "Trimestral",
"weekly": "Semanal",
"yearly": "Anual",
"dayOfMonth": "Dia do mês",
diff --git a/frontend/src/locales/pt-PT.json b/frontend/src/locales/pt-PT.json
index b149c62f..e885d8d4 100644
--- a/frontend/src/locales/pt-PT.json
+++ b/frontend/src/locales/pt-PT.json
@@ -778,6 +778,7 @@
"income": "Entrada",
"frequency": "Frequência",
"monthly": "Mensal",
+ "quarterly": "Trimestral",
"weekly": "Semanal",
"yearly": "Anual",
"dayOfMonth": "Dia do mês",
diff --git a/frontend/src/locales/ru.json b/frontend/src/locales/ru.json
index 4de871e5..2adac992 100644
--- a/frontend/src/locales/ru.json
+++ b/frontend/src/locales/ru.json
@@ -778,6 +778,7 @@
"income": "Доход",
"frequency": "Частота",
"monthly": "Ежемесячно",
+ "quarterly": "Ежеквартально",
"weekly": "Еженедельно",
"yearly": "Ежегодно",
"dayOfMonth": "День месяца",
diff --git a/frontend/src/locales/uk.json b/frontend/src/locales/uk.json
index dbdb2cb5..98e4cd86 100644
--- a/frontend/src/locales/uk.json
+++ b/frontend/src/locales/uk.json
@@ -778,6 +778,7 @@
"income": "Дохід",
"frequency": "Частота",
"monthly": "Щомісяця",
+ "quarterly": "Щоквартально",
"weekly": "Щотижня",
"yearly": "Щороку",
"dayOfMonth": "День місяця",
diff --git a/frontend/src/pages/recurring.tsx b/frontend/src/pages/recurring.tsx
index 3bd74841..d42837a5 100644
--- a/frontend/src/pages/recurring.tsx
+++ b/frontend/src/pages/recurring.tsx
@@ -137,7 +137,7 @@ function RecurringTab() {
})
const frequencyLabel = (f: string) => {
- const map: Record<string, string> = { monthly: t('recurring.monthly'), weekly: t('recurring.weekly'), yearly: t('recurring.yearly') }
+ const map: Record<string, string> = { monthly: t('recurring.monthly'), quarterly: t('recurring.quarterly'), weekly: t('recurring.weekly'), yearly: t('recurring.yearly') }
return map[f] ?? f
}
@@ -359,13 +359,14 @@ function RecurringForm({
<div className="grid grid-cols-2 gap-4">
<div className="space-y-2">
<Label>{t('recurring.frequency')}</Label>
- <select className={selectClass} value={frequency} onChange={(e) => setFrequency(e.target.value as 'monthly' | 'weekly' | 'yearly')}>
+ <select className={selectClass} value={frequency} onChange={(e) => setFrequency(e.target.value as RecurringTransaction['frequency'])}>
<option value="monthly">{t('recurring.monthly')}</option>
+ <option value="quarterly">{t('recurring.quarterly')}</option>
<option value="weekly">{t('recurring.weekly')}</option>
<option value="yearly">{t('recurring.yearly')}</option>
</select>
</div>
- {frequency === 'monthly' && (
+ {(frequency === 'monthly' || frequency === 'quarterly') && (
<div className="space-y-2">
<Label>{t('recurring.dayOfMonth')}</Label>
<Input type="number" min="1" max="31" value={dayOfMonth} onChange={(e) => setDayOfMonth(e.target.value)} />
diff --git a/frontend/src/types/index.ts b/frontend/src/types/index.ts
index 85f4c28b..12687a81 100644
--- a/frontend/src/types/index.ts
+++ b/frontend/src/types/index.ts
@@ -431,7 +431,7 @@ export interface RecurringTransaction {
amount: number
currency: string
type: 'debit' | 'credit'
- frequency: 'monthly' | 'weekly' | 'yearly'
+ frequency: 'monthly' | 'quarterly' | 'weekly' | 'yearly'
day_of_month: number | null
start_date: string
end_date: string | null