Recurring transactions - Sure Docs (draft)

Overview

The recurring transactions feature automatically identifies patterns in your transaction history to detect recurring charges like subscriptions, regular payments, and bills. Once identified, these transactions are displayed in your transaction list with projected upcoming charges. The Bills surface — which includes the pay-run overview, calendar view, paycheck planner, and AI helpers described below — is a preview feature. Each family member must enable preview features in Settings → Preferences before they can access it. The underlying recurring transaction detection and settings pages are available without the preview flag.

How it works

Automatic pattern detection

Pattern detection analyzes your transaction history to identify recurring patterns based on:

Merchant matching: Groups transactions by the same merchant
Amount consistency: Looks for transactions with the same amount
Date clustering: Detects transactions that occur on similar days each month (within a 5-day window)
Minimum occurrences: Requires at least 3 occurrences in the last 3 months
Recent activity: Last occurrence must be within the last 45 days

The pattern detection uses circular distance calculations to handle month-boundary cases (e.g., transactions on days 28, 29, 30, 31, 1, 2 are recognized as a single recurring pattern).

Investment and crypto account exclusion

Transactions in Investment and Crypto accounts are never considered as bill or income candidates, even when a provider reports them as plain transactions rather than trades. Brokerage and retirement feeds often deliver dividends, reinvestments, and 401k contributions as regular transaction rows on a fixed monthly cadence and in tightly clustered amounts — the exact shape the detector looks for. Without this exclusion, a monthly 401k contribution would be detected as recurring income (because it is an inflow to that account), which inflates cash-flow projections. The Trade entryable type is also excluded separately, so investment activity is filtered regardless of how a provider reports it. Any previously detected series that originated from an Investment or Crypto account are automatically retired (ended) on upgrade. Their paid, skipped, and missed occurrences are preserved as historical records, but future occurrences are removed and the detector will not recreate the series.

When patterns are identified

Pattern identification runs automatically after:

CSV imports complete (transactions, trades, accounts, etc.)
Any provider sync completes (Plaid, SimpleFIN, LunchFlow, etc.)
Manual identification via the recurring transactions settings page

Projected transactions

Active recurring transactions appear at the top of your transaction list showing:

Expected upcoming charges for the next month
Merchant name and logo
Projected amount
Expected date based on historical patterns
“Projected” badge to distinguish from actual transactions

Projected transactions only appear when no filters are applied to the transaction list. The projected recurring list is cached per user and refreshed automatically when any of the following change: your recurring transactions, account statuses, the merchants attached to your recurring transactions, or your account sharing access. The cache also resets at the start of each new day, since the list shows charges due within the next 10 days. Only recurring transaction IDs are stored in the cache. The full records are loaded fresh on every request using those IDs, and account access is re-verified at that point. This means a series moved to an account you no longer have access to is excluded immediately, even if a cache entry was written just before the change. It also means the cache remains valid across application upgrades that add new columns to recurring transactions — stale cached objects that predate a schema change will not cause errors.

Account scoping

Recurring transactions respect account sharing and permissions: What you see:

Recurring transactions are scoped to accounts you have access to
Only recurring patterns from your owned and shared accounts appear in your list
Projected transactions only show for accounts you can view

Pattern detection:

Pattern identification analyzes only transactions from accounts you have access to
Shared accounts contribute to recurring pattern detection based on your permissions
Each family member may see different recurring transactions based on their account access

This ensures that recurring transaction detection respects your account sharing configuration and privacy settings.

Managing recurring transactions

Settings page

Access recurring transaction management at Settings → Recurring. The settings page displays:

Merchant: The merchant name and logo
Amount: The recurring charge amount
Expected day: The day of month when the charge typically occurs
Next date: The next expected occurrence date
Last occurrence: When the transaction last occurred
Status: Active or inactive
Actions: Toggle status or delete

When detection finds recurring inflows (such as a regular paycheck), those are classified as income suggestions rather than bill suggestions. Income suggestions do not appear in the Bills overview. They appear in a separate strip on Settings → Recurring with wording that reflects their nature as income. Confirming an income suggestion adds it as an income series, not a bill.

Manual actions

Identify patterns

Click Identify Patterns to manually trigger pattern detection. This analyzes your transaction history and creates or updates recurring transaction records. Running this multiple times will not create duplicates.

Clean up stale

Click Clean Up Stale to mark recurring transactions as inactive if they haven’t occurred recently. Staleness is measured in the series’ own cycles — two missed cycles of the cadence — so quarterly and annual bills are not incorrectly retired just because they have long gaps between normal occurrences. The minimum floor is 2 months for automatically detected patterns and 6 months for manually marked patterns. Recurring transfers are matched by their transfer pair (an outflow on the source account paired with an inflow on the destination account) rather than by name, so transfers stay active as long as the pair keeps occurring and are retired only when the pair stops.

Toggle status

Use the play/pause icon to manually activate or deactivate a recurring transaction. Inactive transactions won’t show projected charges.

Delete

Use the trash icon to permanently remove a recurring transaction record.

Mark as recurring

You can manually mark any individual transaction as recurring from the transaction detail view. Click Mark as Recurring to create a manual recurring transaction. The system automatically calculates amount variance from the past 6 months of similar transactions, allowing it to track recurring charges that vary in amount (like utility bills). Two manual recurring entries for the same payee are allowed as long as their amounts differ (for example, a

3.00 fee and a

19.68 charge from the same merchant). An exact duplicate — same account, payee, currency, and amount — is still blocked.

Create a bill from a transaction

With preview features enabled, Create a bill appears alongside Mark as Recurring in the detail view for a transaction that is not a split child. It opens the declaration dialog with the merchant name (or transaction name when there is no merchant name), absolute amount, account, currency, and a projected next due date filled in. These fields can be adjusted before saving. An income transaction opens an income declaration instead of a bill. This is the fastest path for declaring a bill you can already see in your transaction history. The dialog requires preview features to be enabled under Settings → Preferences.

Schedules and cadences

Recurring transactions support a range of cadences beyond monthly:

Cadence	Description
Monthly	Once per month on a given day (e.g., the 15th)
Weekly	Once per week on a given weekday
Biweekly	Every two weeks on a given weekday
Semimonthly	Twice per month on two fixed days (e.g., the 1st and 15th)
Quarterly	Every three months on a given day
Semiannual	Every six months on a given day
Annual	Once per year on a given month and day
Custom interval	Every N weeks, months, or years (1–99), for cadences not covered by a named preset

When a recurring transaction uses an interval-based cadence (biweekly, quarterly, semiannual, or a custom interval), an anchor date is required to establish the phase of the schedule.

Custom intervals

The frequency picker includes a Custom interval option that lets you set a bill to repeat every N weeks, months, or years, where N is any whole number from 1 to 99. Use this for cadences that named presets do not cover — for example, every 3 weeks, every 2 months, or every 2 years. When you enter a custom interval, the value must be a whole number. Decimal values (e.g. 2.5) and non-numeric input (e.g. 3abc) are rejected with a validation error. If the interval you enter matches a named preset — for example, every 3 months is the same schedule as quarterly — the app treats it as that preset. Reapplying the same cadence is a no-op. Custom intervals are not available to the assistant’s create_bill and update_bill tools, which accept only the named preset cadences.

Recurrence rule validation

Each cadence has field requirements that are enforced when you save a recurring transaction. Validation errors are returned in your configured display language (set under Settings → Preferences → Language). The rules by frequency:

Weekly — requires a weekday. Day of month and week-of-month ordinal are not allowed.
Monthly — requires exactly one of: a day of the month (1–31, or -1 for the last day) or a weekday. When a weekday is set, a week-of-month ordinal is also required.
Yearly — same as monthly, plus a month of year is required.

If you submit a schedule that violates these constraints, the app returns a validation_failed error with a localized message describing the specific field and rule that failed.

Weekend adjustment

When a bill falls on a weekend you can choose how the due date adjusts:

None: No adjustment; the bill is due on the scheduled date regardless of day of week
Skip: The occurrence is skipped entirely on weekends
Before: The due date moves to the preceding Friday
After: The due date moves to the following Monday

End conditions

A recurring transaction can be set to end in three ways:

Never: The series continues indefinitely
On date: The series ends on a specific calendar date
After count: The series ends after a fixed number of occurrences (up to 600)

Bill types

Each recurring transaction carries a type that describes the nature of the series:

Type	Description
Bill	A recurring expense you owe, such as rent or utilities
Subscription	A recurring charge for a service, like a streaming plan
Installment	A fixed-count payment plan, such as loan installments
Income	A recurring inflow, such as a salary or dividend
Transfer	A recurring move between your own accounts (set automatically)
Other	Anything that doesn’t fit a specific category

Transfers are typed automatically when the recurring transaction has a destination account.

Bill fields

Currency

When you create a new bill, the amount field includes a currency picker. It defaults to your family’s currency, or to the transaction’s currency if you are starting the bill from an existing transaction. Once a bill is saved, its currency is fixed and shown read-only when you edit it. The amount input step follows the selected currency, capped at four decimal places: JPY uses whole units, USD uses two decimal places, and BTC uses four. Bill amounts are stored to four decimal places. Validation rejects meaningful precision beyond that storage limit rather than silently rounding it; the server does not separately impose each currency’s display precision.

Payment URL

You can store a payment link on a bill. When set, you can open the link directly from the bill drawer to navigate to the payment portal.

Autopay

Mark a bill as autopay to indicate that the payment is handled automatically. Autopay bills still appear in your bill list but are not flagged as requiring action. On the overview, autopay rows are visually de-emphasized: the name and amount are shown in a secondary color rather than full contrast, making it easy to focus on bills that still need attention.

Notes

Free-text notes stored on the recurring transaction for your own reference.

Status lifecycle

A recurring transaction moves through the following statuses:

Status	Meaning
Suggested	Detected by pattern matching; waiting for your confirmation before generating projected occurrences
Active	Live and generating projected upcoming charges
Paused	Temporarily suspended by you; resumable
Inactive	Automatically retired by the system after going stale
Ended	Reached its end condition, was cancelled, or was dismissed from the suggestion queue. The detector will not recreate an ended series.

The API accepts only active and inactive on write. The other statuses are owned by the detection pipeline and the UI.

Bills

The Bills surface is a pay-run workspace that lets you see, pay, and plan around your recurring obligations. It is available to family members who have enabled preview features. The Bills page title, navigation tabs, and action buttons (New bill, New income, Review with AI) display in the language you have set in Settings → Preferences. Due dates shown in bill rows — in the date rail, the “Next up” strip, and the subline on narrow screens — also follow your locale. Locales that use day-first order (such as French, Polish, and Russian) show dates in that order, and any date that falls in a future year includes the year.

Header and actions

The Bills page header follows the same layout as the Transactions page. An overflow menu appears on the left side of the action area, and the primary action button appears on the right. The overflow menu contains:

The secondary add action (New bill when on the Paycheck view; New income on all other views)
Review with AI (when an LLM provider is configured and AI features are enabled)

The primary action button is:

A labeled button on wider screens (New bill, or New income on the Paycheck view)
A round + button on narrow viewports, with the action name as its accessible label

The Bills page also has a page heading (“Bills”) at the top of the header, giving screen readers a landmark to navigate to.

Views

The Bills page offers four views, switchable from the view switcher at the top of the page:

Overview — your current month at a glance. A banner for detected series awaiting review can appear first. When there are overdue, due-this-month, or upcoming bills, the pulse and AI prompt chips precede the bill list. The list orders sections as Needs attention, This month, After this month, and Paused. Payment-match reviews, suggested series, and notices follow the list. Bills are grouped by their effective due date (the later of the original due date and any snoozed date) and, when you have declared income, marked with pay-period boundaries so you can see which paycheck covers which bill. Each boundary band shows the paycheck label and the total due before the next payday. On narrow list widths — such as on a phone, or on a desktop with both sidebars open — the label and total stack vertically so neither wraps. A “Next up” strip shows the next few upcoming occurrences; select View calendar to open the Calendar view. The overview shows only payable series (bills, subscriptions, installment payments, and debt repayments) — detected income and transfers do not appear here. Banners, notices, and payment suggestions on the overview are scoped to this same set of payable series. Every row in every section shows a date rail on the left when the bill list is wide enough. On narrow screens (phones, or desktop windows with both sidebars open) the date rail is hidden; the row’s subline leads with the same date instead — for example, “Sep 22 · Monthly on the 22nd” or “Today · Amount changed” — so the due date is always visible regardless of screen width. Dates in a future year include the year on a second line inside the rail so they do not wrap mid-date. When you have no overdue, due-this-month, or upcoming bills, the month summary and AI prompt chips are hidden and the page shows an empty state instead. Paused bills do not trigger the pulse or chips, because they owe nothing this month. Detected suggestions that are not yet confirmed do not count as bills for this purpose. The overview also shows a Needs review queue for suggested payment matches and a Possible new bills strip for suggested series. On wider screens each row in those strips shows the description and review action buttons side by side. On narrow screens (phones, or a desktop with both sidebars open) the buttons drop below the description so the full bill name is readable without truncation. Detected income suggestions are excluded from the overview and reviewed in a separate strip under Settings → Recurring. Below the bill list, the overview shows up to three action sections in this order, each with a labeled heading and item count:
- Needs review — suggested payment matches. Each row shows the suggested transaction and the bill it was matched to, with Link payment and Not this one actions. On narrow layouts, the review action buttons stack below the text.
- Possible new bills — recurring outflow patterns the detector found but you haven’t confirmed yet. This section is collapsible and remembers whether you left it open or closed on each device. On narrow layouts, the Add bill and Not a bill actions stack below the bill name.
- Changes — notices about upcoming trials converting to paid plans, upcoming renewals, and price changes. Urgent notices appear first. When urgent and routine notices are both present, routine notices collapse under a disclosure; when only routine notices are present, they remain visible.
All — the complete list of active bill series, filterable by status, type, and sort order. The filters and the list share one card, the same way the Transactions page groups its filters and list. Each row shows the merchant logo or initials, the bill name over a schedule subline (type and cadence), the amount, and the next due date. For paused or dismissed bills, the status replaces the due date. Income bills display the amount in green. Clicking anywhere on a row opens the bill drawer. On wider screens the list is a scrollable table with four columns (name, next due, amount, actions); on narrower screens it switches to a compact list.
Calendar — upcoming bills laid out on a monthly calendar. The month navigation controls sit on the page background. The month totals, the calendar grid (or agenda list on mobile), and the iCal subscription links all sit on a shared card surface. The card heading shows the total bill count for the month.
Paycheck planner — upcoming bills apportioned across your next pay periods (see Paycheck planner below).

Throughout the Overview and Paycheck planner, bills use the later of their original due date and any snoozed date. A bill snoozed to a future month moves out of the current month’s totals and into the month it will actually be due. Clicking anywhere on a bill row in the Overview, or on a Next up item, opens the bill in the right-hand drawer. Modifier clicks (Cmd/Ctrl) open the bill in a new tab. Navigating directly to a bill URL (for example, /bills/:id) opens the same drawer over the Bills overview. When a current occurrence is available, the bill summary drawer leads with its remaining balance or paid amount. A smaller line shows the amount paid, the expected total, and the due label. If the amount is estimated and the series has a known range, that range appears below the figure at all widths, including on phones. Without a current occurrence, the summary shows the series amount and, when known, the next expected date. A cancellation notice appears above the figure when a cancellation date is recorded but the series is still active. The bill drawer is the complete bill surface. It shows the bill summary at the top, followed by collapsible sections — Overview (12-month chart, per-year totals, price changes), Coming up (upcoming due dates), History (settled cycles and what paid each one), and Notes. Coming up, History, and Notes appear when they have content. The deep sections load lazily when you scroll to them. Edit, Pause/Resume, and Delete are available from a menu in the drawer header, next to the close button. AI configure appears there when you have enabled AI and an LLM provider is available.

Bill row subline

Each bill row shows a single subline with context about that occurrence. The subline follows a fixed order, truncating from the end when space is tight:

Due date (narrow screens only, in the same color as the date rail)
Autopay (only when the bill is active and set to autopay — paused bills do not show Autopay)
Attention reason (see below)
Payment N of M (for installment plans)
Debt payment (for transfer-type series)
Frequency
Account

Attention reasons — when a bill needs action, the subline names the specific reason. Only the overdue reason is shown in red; other reasons (such as “Match needs review” or “Partial”) remain uncolored even when the bill is also overdue. For a paused bill, the subline shows “Paused” regardless of whether there is an unpaid occurrence. Amount changed — a price-change notice appears only when the bill’s amount has shifted by 10% or more within the last 30 days. Smaller changes do not surface in the row. Estimated amount range — On wider lists, an estimated, unpaid bill with a known amount range shows that range beneath the amount. On narrow screens this is hidden; open the bill drawer to see the full range.

Row actions

On wider screens, each bill row in the Overview reserves a fixed slot at the trailing edge for an action. A row shows an action only when the bill needs you now. The first matching rule applies:

No action — the bill is paused, or the occurrence is already settled.
Review match — a payment suggestion is waiting, regardless of due date.
Add payment — the occurrence has been partially paid and is still within its payment window.
No action — the bill is on autopay and is not yet overdue (autopay will handle it).
Pay — the bill has a payment portal URL and the occurrence is within its payment window.
Find payment — no payment portal URL is set and the occurrence is within its payment window.
No action — the occurrence is outside the payment window.

On narrow screens (phones, or a desktop with both sidebars open) rows carry no action. The row’s subline describes why the bill needs attention, and tapping anywhere on the row opens the drawer. The occurrence drawer always shows an action, regardless of screen size.

Occurrence drawer

Calendar entries and bill links in pay-period lists open the occurrence drawer — the action surface for resolving that specific billing cycle. Overview rows and Next up items open the bill drawer. Actions such as Review match or Record payment open the occurrence drawer; Pay opens the bill’s payment link. The occurrence drawer shows:

Due label — a context-aware label describing when the payment is due. The label adapts to the occurrence’s state: overdue (with the number of days past due), due today, due in N days, snoozed until a date, or the original due date if the cycle is already settled. For an open occurrence in a non-active series (paused or dismissed), the label leads with the series status — for example, “Paused · Due Sep 10” — rather than showing an overdue count. Paused bills omit Autopay from the bill row and drawer’s schedule subline.
Payment progress — the amount paid so far, the expected amount, and a progress ring. The headline reads the current state: the paid amount if fully paid, “Skipped”, “Marked missed”, or the remaining balance.
Linked payments — any transactions already allocated to this occurrence, each with an unlink option.
Candidate matching — when the occurrence is still open, the drawer surfaces the most likely matching transaction from your accounts as a card with a single “Link payment” action. Other likely matches appear below it. You can also search all transactions by name. For recurring transfers, the engine matches the outflow leg of a transfer between the series’ source and destination accounts rather than matching by name or merchant.
Manual payment — if no matching transaction exists, a disclosure panel lets you record a payment using a styled money field and date picker, without linking a bank transaction.
Quick actions — mark paid (settles the remainder without recording a transaction), skip, snooze for one week, and reopen (for already-settled or skipped occurrences). Snoozing moves the bill to its new date across the overview, pay-period groupings, and the “Next up” strip — a bill snoozed into the following month moves out of this month’s total entirely.

All labels and feedback messages in the occurrence drawer — including the due label states, payment summaries, and action confirmations — are displayed in your configured display language (set under Settings → Preferences → Language).

Recording payments

From the bill drawer you can apply a payment to the current occurrence in several ways:

Link a transaction — select an existing transaction from your accounts to record as the payment. If the transaction is in a different currency, the app converts at the exchange rate for that transaction’s date.
Manual payment — enter an amount and date directly, with no transaction linked.
Partial payment — enter a custom amount less than the full due amount to record a partial payment. You can add more payments until the occurrence is fully covered.

When the app cannot record a payment it shows an error message. Common reasons:

Over-allocation — the amount you entered would exceed the total of the linked transaction.
Missing exchange rate — the transaction is in a different currency and no exchange rate is available for that date. Enter the amount explicitly to work around this.
Already applied — the transaction has already been applied to this bill.

To remove a payment, use the unlink action in the payment history section of the drawer. Suggested payments — the matching engine may automatically suggest a transaction for an open occurrence. You can confirm the suggestion to apply it or dismiss it. Dismissing a suggestion marks that transaction so it will not be suggested for the same bill again. Suggestions appear only for occurrences the overview currently lists; occurrences from ended bills or outside the visible window are not surfaced. Recurring transfers are matched by their account pair: the engine looks for the outflow leg of a transfer from the series’ source account into its destination account. This means a mortgage payment or card payment that you have marked as recurring will receive automatic payment suggestions the same way a regular bill does. All payment feedback messages — confirmations and errors — appear in your configured display language. When a transaction is linked to a bill, the Applied to section on the transaction detail view shows the bill name and occurrence due date. That date is displayed in your configured language as well.

Paycheck planner

The paycheck planner slices your upcoming bills across the pay periods defined by your declared income. Only manually declared income series (bill type income, set to manual) define pay periods; automatically detected inflows do not. Bills are sorted and filed by their effective due date — the later of the original due date and the snoozed date, if any. A bill snoozed past a payday is filed under the pay period it will actually be due in rather than the one that precedes it. For each pay period the planner shows:

The payday date and the income arriving in that period
The safe-to-spend headroom (or shortfall, if obligations exceed income) as the headline figure for that period
A three-column breakdown showing bills due this period, bills reserved for later, and the safe or short amount
An allocation bar tied to the breakdown columns by colored swatches
Bills due inside the period and their share of that paycheck
Bills due in a later period that are too large for their own paycheck and have a reserved slice held back from this period

The allocation bar is shown for periods with positive income. Its segments and swatches change depending on whether the period is short:

Normal period — the bar has up to three segments: due (high contrast), reserved (muted), and safe (green). Zero-value segments are omitted; each breakdown column has a swatch only when its segment is present.
Short period — the bar splits into two segments: covered (muted, the portion income reaches) and short (red, the gap). Only the short column gets a swatch, because only the shortfall has a corresponding segment on the bar. The due and reserved columns still show their figures but without swatches.

A leading window covers the time between today and the next payday. It has no income, so shortfalls in that window are measured against your cash on hand (the sum of your visible depository accounts, excluding tax-advantaged accounts). When the balance cannot be determined, the window is shown without any cash-based judgment — neither the shortfall warning nor the covered-with-items note appears. The income schedule summary appears as a card above the pay periods. It shows an eyebrow label (“Income”), the next payday headline, and a Manage control that expands to list each income series with its frequency, next payday, and amount. This section was previously a bare disclosure that sat directly on the page background. To use the paycheck planner, create at least one recurring transaction with bill type income and the manual flag set.

Calendar feed

You can subscribe to your bills in any calendar app that supports ICS feeds (Google Calendar, Apple Calendar, Outlook, and others). To get your feed URL, go to Bills → Settings (or the bills feed section of your account settings) and copy the calendar link. The feed covers the next 90 days of open, active bill occurrences and updates automatically. Key properties of the calendar feed:

Sessionless and token-authenticated — the URL can be shared with a calendar app without logging in each time.
Per-member scoping — the feed reflects only the bills you can see based on your account-sharing permissions.
Revocable — resetting the feed token invalidates all previously shared URLs immediately. Any calendar app using the old URL will stop receiving updates until it is given the new URL.
Preview-gated — the feed endpoint returns 404 if preview features are disabled for your account or if recurring transactions are disabled for your family.

AI helpers

Several in-page AI helpers are available when an LLM provider is configured and you have AI features enabled in your account. Quick-prompt chips — shortcut buttons that seed the AI chat sidebar with a pre-written question about your bills. Clicking a chip opens the sidebar and starts a conversation without you typing anything. The Overview shows three chips:

“What’s due before my next paycheck?”
“Which subscriptions went up this year?”
“What am I paying monthly for subscriptions?”

The Paycheck planner shows two chips:

“What’s due before my next paycheck?”
“How much is safe to spend this period?”

The Paycheck planner chips only appear when you have at least one declared income schedule. Without declared income there is no pay period or paycheck to ask about, so the chips are hidden. Smart fill — when you add a new bill from the Bills page and pick an existing transaction as the starting point, the smart fill button analyzes that transaction’s charge history and proposes the bill name, amount, cadence, due day, and autopay status. You review and adjust the proposal before saving. Smart configure — in the bill drawer, the smart configure button reads the bill’s own charge history and proposes corrections to any fields that the history contradicts (for example, a different due day or amount). Only fields where the history suggests a change come back with a proposal; everything else is left as is. You review the proposal in a dialog and apply only the changes you accept. All helpers require the family’s LLM provider to be configured. They are not available on self-hosted installs without a provider set up.

Assistant and MCP tools for bills

When preview features are enabled and an LLM provider is configured, the assistant and any connected MCP client can interact with your bills using a set of dedicated tools. The tools are absent from the tool list until preview features are turned on. All bill tools share a consistent error contract: if a call fails, the response includes an error message and a hint explaining how to recover or retry.

Read tools

get_bills — returns your bills, subscriptions, and other recurring obligations, each with its current occurrence’s payment state. Accepts optional filters:

Filter	Description
`status`	Series lifecycle: `active` (default), `suggested`, `paused`, `ended`, or `all`
`payment_state`	Current occurrence state: `overdue`, `due`, `upcoming`, `partial`, or `paid`. Non-active bills never match `overdue` or `due`. Their open occurrence `state` returns the displayed lifecycle status: `"paused"` for paused or inactive series, and `"ended"` for ended series.
`bill_type`	Kind of obligation (e.g. `bill`, `subscription`, `installment`, `income`)
`search`	Substring match on the bill or merchant name
`due_within_days`	Only bills whose next due date falls within this many days (1–365)

The response includes per-currency totals (active monthly equivalent spend, overdue count) computed over the full filtered set, not just the page shown. When the result is empty, get_bills checks whether bills exist under other statuses and returns a hint pointing there. For an open occurrence, current_occurrence.state is schedule-derived when the series is active (overdue, due, or upcoming). For a non-active series, it returns the displayed lifecycle status instead: "paused" for paused or inactive series, and "ended" for ended series. Settled occurrences retain paid, skipped, or missed regardless of the series lifecycle status. Use the status filter to find bills by lifecycle state. get_bill_details — returns one bill’s full story: configuration, every open occurrence, the last 12 settled occurrences with their payments, upcoming due dates for the next 400 days (first 3), price-change history (24-month window), and cost analytics. Analytics are derived from confirmed payments only, never from estimates. Pass the exact bill_id returned by get_bills. get_bill_audit — a deterministic review of your bills that surfaces:

Possible duplicates — series with the same name, amount, and due day
Price changes — over a configurable lookback window (default 12 months, max 24)
Upcoming trials — trials converting within 30 days
Upcoming renewals — renewals due within 30 days
Long overdue — bills overdue by at least one full billing cycle in the series’ own cadence
Dormant — paused bills still carrying unpaid occurrences
Awaiting confirmation — detected series not yet confirmed by the user
Undeclared candidates — recurring outflow patterns not yet declared as bills

Each section reports items, count, and truncated (capped at 20 items). The audit returns facts; the assistant narrates and prioritizes them. get_paycheck_plan — slices upcoming bills across pay periods defined by your declared income schedules. Returns up to 6 pay periods (default 3), each showing income, bills due, bills reserved for a later period, and safe-to-spend headroom. Each bill item includes both due_on (the original scheduled date) and effective_due_on (the later of the original due date and any snoozed date), so the assistant can show the date the user will actually see. When detected series are excluded because they are still awaiting confirmation, the response notes how many were left out so the assistant can caveat the headroom figure. Only manually declared income series (bill type income) define pay periods. Automatically detected bank inflows do not.

Write tools

All write tools confirm their arguments strictly and return a clear error rather than guessing at ambiguous input. create_bill — creates a bill, subscription, installment plan, or income schedule. Required fields: name, amount (always a positive magnitude), and first_due_on (seeds the due-day anchor). Optional fields include frequency, is_income, bill_type, account_name, category_name, autopay, payment_url, and notes. The frequency field accepts the named preset cadences only (monthly, weekly, biweekly, semimonthly, quarterly, semiannual, annual). Custom intervals cannot be set through this tool. Unrecognized frequency values are rejected with the list of valid cadences rather than silently defaulting to monthly. update_bill — updates one bill’s configuration. Pass only the fields being changed. Amount changes apply forward only; occurrences already due keep their original figure. Changing the frequency pins the schedule so automatic detection respects it as the user’s intent. status accepts active or paused. record_bill_payment — records a payment against a bill’s open occurrence. Omit amount to settle in full; pass amount for a partial payment. The tool rejects an amount that exceeds the remaining balance on the occurrence. Linking to a specific bank transaction is not possible here; the app’s matching engine owns that flow.

Prerequisites

Preview features must be enabled in Settings → Preferences
An LLM provider must be configured
Recurring transactions must not be disabled for the family (Settings → Recurring transactions)

Pattern clustering

The pattern detector uses circular distance calculations to handle month-boundary patterns:

Days are normalized on a circular scale (1–31)
Clustering accounts for wrap-around (e.g., day 31 to day 1 is distance 1)
Standard deviation threshold of 5 days for clustering
Median calculation on rotated day sequences for accurate expected day

Amount variance filtering

When building or refreshing a manual recurring entry’s expected amount range, only historical transactions whose amount is within 2× of the anchor amount (double or half) are included. This prevents unrelated charges from the same merchant — for example, a small fee and a larger monthly due — from being blended into a single projected amount that matches neither real transaction.

Cleanup logic

Recurring transactions are automatically marked inactive when no matching transaction has occurred within two cycles of the series’ own cadence, subject to a minimum floor:

Automatically detected patterns: minimum 2 months
Manually marked patterns: minimum 6 months

This means a quarterly bill is not retired after two months of silence — it is allowed two full quarters of inactivity before being considered stale. An annual bill is given two full years. For recurring transfers, matching uses transfer-pair detection (an outflow on the source account paired with an inflow on the destination account, within the usual amount and day-of-month tolerance) so transfers stay active while the pair recurs and are retired only when the pair stops.

Data storage

Each recurring transaction record stores:

Family, account, and merchant associations
Amount and currency
Bill type
Expected day of month (1–31)
Anchor date (required for interval-based cadences)
Last occurrence date
Next expected date
Status
Occurrence count
Payment URL, autopay flag, and notes
End condition (never, on date, or after count)
Weekend adjustment rule

Self-hosting maintenance

When detection runs

The full pipeline (detect patterns, materialize upcoming occurrences, repair provider-replaced entries, match payments, detect price changes) runs automatically:

After every completed bank sync or import (debounced by 30 seconds)
Nightly at 05:30 UTC for families that never sync

You can also trigger it on demand using the Find recurring transactions button on an empty Bills page, or Identify Patterns under Settings → Recurring transactions.

First run on existing data

The user-triggered detection actions backfill the last six months of history: past occurrences are generated and closed as paid where a real transaction anchors them. Past occurrences with no matching transaction are deleted rather than shown as missed, so the backfill reconstructs history without fabricating debt. The backfill is idempotent, so re-running detection never duplicates history. Background syncs never backfill. On an instance upgraded from a build without the Bills subsystem, run either detection action once to reconstruct history.

Maintenance tasks

These tasks are safe to re-run. They only close history a real entry anchors and never touch existing payment records.

# Rebuild N months of occurrence history for every family (default 6)
bin/rails "recurring:backfill_history[12]"

# One-shot classification of auto-detected series still on defaults
# (assigns bill/subscription/installment kind and a category)
bin/rails recurring:classify_existing

Use cases

Subscription tracking

Monitor recurring subscriptions like:

Streaming services (Netflix, Spotify, etc.)
Software subscriptions (Adobe, Microsoft 365, etc.)
Membership fees (gym, clubs, etc.)

Payment and bill management

Track regular payments and bills such as:

Utilities (electricity, water, gas)
Insurance premiums
Rent or mortgage payments

Income tracking

Identify recurring income like:

Salary deposits
Freelance client payments
Investment dividends

Limitations

Requires at least 3 occurrences in the last 3 months for automatic detection
Last occurrence must be within 45 days for automatic detection
Transactions in Investment and Crypto accounts are excluded from bill and income detection
Amount variance for manual recurring entries is bounded to 2× the anchor amount; charges outside that range are treated as separate recurring entries
Bill amounts are stored to four decimal places; meaningful precision beyond that storage limit is rejected with a validation error
Projected transactions are hidden when filters are applied
Pattern detection is event-driven (runs after syncs or manual triggers), not continuous or real-time
Interval-based cadences (biweekly, quarterly, semiannual, and custom intervals) require an anchor date
Custom interval values must be whole numbers between 1 and 99; decimal or non-numeric input is rejected
Custom intervals are available in the app UI but not through the assistant’s create_bill or update_bill tools
The API writes only active and inactive status; other statuses are managed by the detection pipeline

​Overview

​How it works

​Automatic pattern detection

​Investment and crypto account exclusion

​When patterns are identified

​Projected transactions

​Account scoping

​Managing recurring transactions

​Settings page

​Manual actions

​Identify patterns

​Clean up stale

​Toggle status

​Delete

​Mark as recurring

​Create a bill from a transaction

​Schedules and cadences

​Custom intervals

​Recurrence rule validation

​Weekend adjustment

​End conditions

​Bill types

​Bill fields

​Currency

​Payment URL

​Autopay

​Notes

​Status lifecycle

​Bills

​Header and actions

​Views

​Bill row subline

​Row actions

​Occurrence drawer

​Recording payments

​Paycheck planner

​Calendar feed

​AI helpers

​Assistant and MCP tools for bills

​Read tools

​Write tools

​Prerequisites

​Pattern clustering

​Amount variance filtering

​Cleanup logic

​Data storage

​Self-hosting maintenance

​When detection runs

​First run on existing data

​Maintenance tasks

​Use cases

​Subscription tracking

​Payment and bill management

​Income tracking

​Limitations