Import Rules
Auto-categorize imported transactions using pattern-based rules with a visual query builder, so you spend less time manually sorting transactions and more time understanding your finances.
Overview#
Import Rules let you define conditions that automatically assign categories, tags, vendors, and other fields to transactions as they are imported. Rules use a visual query builder with boolean logic, support multiple actions per rule, and can be previewed or applied retroactively to existing transactions.
Creating a Rule#
- Navigate to Budget > Rules
- Click Add Rule
- Give the rule a descriptive name (e.g., "Amazon purchases", "Monthly rent")
Building Criteria#
Each criterion consists of three parts:
| Component | Options |
|---|---|
| Field | Description, Vendor, Amount, Date, Reference, Notes, Transaction Type, Account, Account Type, Import Source |
| Match type | Contains, Equals, Starts with, Ends with, Regex for text; Equals, Greater than, Less than, Between for amounts; On date, Before, After, Between dates for dates |
| Pattern | The value to match against |
Tip: Use "Contains" for most text matching. Reserve "Regex" for complex patterns where simpler match types won't suffice.
A Regex pattern uses PHP's regular expression syntax (PCRE) and ignores case, so amazon|ebay matches AMAZON MARKETPLACE. To set the flags yourself, write the pattern as /pattern/flags: /^ORDER-\d+$/ matches case-sensitively and /café/iu ignores case in non-English text as well. The pattern is checked when you save the rule, and one that isn't valid is refused with the reason.
A Between condition on an amount takes the range as {"min": 0, "max": 100}, and Between dates takes the same form with dates: {"min": "2026-01-01", "max": "2026-12-31"}. Both ends are included, and a minimum of 0 is a real bound. A range that cannot be read is refused when you save the rule, rather than saved as a rule that never matches.
Note: Rules built with a Between condition in the visual builder did not match anything in earlier versions, because the range was saved as text. They now match without being saved again.
The Transaction Type field lets you filter by Income or Expense. This is useful when the same description appears as both inflow and outflow (e.g., internal transfers between accounts).
The Import Source field matches how a transaction arrived. The value is one of a fixed set of labels the importer writes, so the pattern must match one of them exactly: CSV Import, OFX Import, QIF Import, camt.053 Import or Bank Sync, or, for a file imported with one of the app presets, Firefly III, YNAB, Actual Budget, Mint, Monarch Money or Toshl. Use it to categorize differently depending on where the data came from — for example, treating bank-sync rows as already reconciled.
Note: The source is only known while a transaction is being imported. It is not stored on the transaction afterwards, so an Import Source condition never matches when you run a rule over existing transactions — see Run on Existing Transactions.
The Account field scopes a rule to one of your accounts — pick the account from the dropdown and the rule only fires for transactions in it. Combine it with a NOT to mean "any account except this one." The related Account Type field matches by kind of account (Checking, Savings, Credit Card, and so on) rather than a specific one — handy for rules like "only on credit-card accounts." Both match when you run a rule over existing transactions and when importing into that account.
Boolean Logic#
Combine multiple conditions using logical operators:
- AND — all conditions must be true
- OR — at least one condition must be true
- NOT — negate a condition or group
Groups can be nested to unlimited depth for complex logic. For example:
(vendor contains "Amazon" AND amount > 50)
OR
(description contains "Prime")
This matches any Amazon purchase over £50, or any transaction mentioning "Prime" regardless of vendor or amount.
Actions#
When a rule matches a transaction, one or more actions are applied:
| Action | Effect |
|---|---|
| Set category | Assign a specific category |
| Set vendor | Set the vendor/payee field |
| Set description | Replace the description, always or only when it is empty |
| Set notes | Add or replace notes |
| Add tags | Attach global tags and category tags (see Adding tags below) |
| Set account | Move the transaction to another of the rule owner's own accounts (see Set account below) |
| Set type | Mark as expense or income |
| Set reference | Set the reference field |
| Regex Replace | Run a regular expression over one text field and write the result into the same field or another one |
| Change Case | Change a text field to UPPERCASE, lowercase, Title Case or Sentence case |
| Replace Text | Replace every occurrence of some text in a field with something else |
| Exclude from Forecast | Mark the transaction as extraordinary so it stays out of forecast projections |
| Auto-Link as Transfer | Find and link a matching opposite transaction as a transfer |
You can configure multiple actions per rule — for example, set the category to "Subscriptions" and add a "streaming" tag simultaneously.
Adding tags#
Add Tags lists your global tags first, then each category's tag sets, named with their category (for example Groceries → Shop). Tick any mix of them.
A rule can match transactions in any category, but a category tag belongs to its own category. So each category tag is added only to matching transactions in that category, and skipped on the rest; the rule's global tags and its other actions still apply to every match. If the same rule also sets the category, the tags are added after it, so a rule that sets Groceries can add a Groceries tag in one go.
Merge with existing tags keeps the tags a transaction already has and adds the new ones. Replace all tags swaps them for the rule's tags.
Set description is handy for turning a bank's raw text, such as CARD PAYMENT TO TESCO STORES 2231, into something readable. Duplicate detection still uses the description from the original file, so importing the same statement again is still recognised after a rule has rewritten it. The same applies to the three text actions below.
Set account#
Set account moves a matching transaction into another account, for example a card payment your bank lists under the wrong account. The account picker in the rule builder only lists the rule owner's own accounts, and a rule pointing anywhere else is refused when it is saved. When the rule runs, a transaction is only moved between two accounts that belong to the same person, and only into one the person running the rule can write to. Your own rules therefore never move a transaction into or out of an account someone has shared with you, and a rule someone has shared with you only moves transactions between its owner's accounts.
Text actions#
Regex Replace, Change Case and Replace Text tidy up the text a bank sends. Each one works on the description, vendor, reference or notes.
Change Case is useful for banks that send everything in capitals, as it turns TESCO STORES into Tesco Stores with Title Case. Replace Text swaps one piece of text for another wherever it appears in the field. The match is exact and case-sensitive, so AMZN is not the same as Amzn.
Regex Replace takes a source field, a target field, a pattern and a replacement. The pattern is written the same way as a Regex criterion, so it ignores case unless you give it your own flags. Every part of the source that the pattern matches is replaced, and the result is written to the target. In the replacement, $1 puts back what the first bracketed group matched, $2 the second and so on. Setting the target to a different field lets you pull part of the description out into it. For example, with the description as the source and the vendor as the target:
| Pattern | ^CARD PAYMENT TO (.+?) \d+ ON .*$ |
| Replacement | $1 |
| Description | CARD PAYMENT TO TESCO STORES 2231 ON 12 SEP |
| Vendor set to | TESCO STORES |
The pattern has to match the whole description for this to work, which is why it starts with ^ and ends with .*$, as anything it does not match is kept in the result. If the pattern does not match at all the target is left alone, so a rule that only fits some of your transactions will not copy the whole description into the vendor of the others. Choose Only if empty to leave the target alone when it already has a value.
The pattern works on letters rather than bytes, so a pattern that cuts text to a length, such as ^(.{20}).*$, never splits a letter like "ü" or "é" in two.
Note: Set category is the one action that skips split transactions. A split’s categories live on its parts, so its own is deliberately empty and a rule leaves it that way — during import, when you run a rule, and when you run a whole group. Every other action still applies to a split.
Auto-Link as Transfer#
The Auto-Link as Transfer action automatically finds a matching transaction on a different account — same amount, opposite type (income vs expense), within a few days — and links the two as a transfer. This is particularly useful for banks that represent internal movements as separate income/expense entries (e.g., Monzo pot transfers).
Example rule for automatic transfer linking:
- Criteria: Transaction Type is Expense AND Description contains "Pot Transfer"
- Action: Auto-Link as Transfer
This works when applying rules manually, during file import, and during bank sync.
Priority#
Each rule has a priority number. Higher priority numbers run first. When multiple rules match the same transaction, the highest-priority rule wins for any conflicting actions.
Tip: Use priority strategically — give specific rules (e.g., "Netflix subscription") a higher priority than general rules (e.g., "All entertainment vendors").
A new rule starts at priority 1. The rules added by Create Default Categories sit at 0, the lowest there is, so any rule you make runs before them. They match whole words in the description only, so "water" does not catch Waterstones; Default Categories lists each one and the words it looks for.
Behavior Settings#
Control how actions interact with existing field values:
| Behavior | Effect |
|---|---|
| Always | Overwrite existing value |
| If empty | Only set the field if it is currently blank |
| Append | Add to the existing value (text fields) |
| Merge | Combine with existing values (for tags) |
Note: "If empty" is useful when you want manual categorization to take precedence over rules.
Preview Matches#
Before saving a rule, click Preview to see which existing transactions in your account would match the criteria. This lets you verify the rule behaves as expected without making any changes.
Tip: If the preview shows unexpected matches, refine your criteria — add more conditions or switch to a more specific match type.
Run on Existing Transactions#
Rules normally apply during import, but you can also apply them retroactively:
- Open the rule you want to apply
- Click Run Rule Now
- Optionally restrict to uncategorized transactions only
- Confirm to apply
Warning: Running a rule with "Always" behavior on existing transactions will overwrite any manual categorization you've previously done on matching transactions.
The Apply Rules button at the top of the Rules page does the same for all your rules at once, over the account and dates you choose. Either way, changes are saved 500 transactions at a time, so a run over a long history is quick, and if the database refuses to save one transaction, only that one is left unchanged. A preview, and the list of what changed afterwards, show the first 500 transactions.
Note: A rule never sets a category on a split transaction, whichever way this option is set. A split has no category of its own — the categories sit on its parts — so writing one onto the whole transaction would count its spending twice. Every other action still applies, so a rule can still set a split's vendor, notes or tags. Splits are shown as Split in the preview and results rather than as uncategorized.
Note: A rule whose criteria include Import Source will not match anything here. The source describes how a transaction arrived and is not kept on the transaction, so it is only available while an import is running.
If a split of yours shows a category: earlier versions let a rule run write one onto a split, leaving a transaction that claims a category while still carrying its own breakdown. Settings › Repair Data finds them — run Scan for Issues and look for Split Transactions Carrying a Category. It clears just the stray category; the transaction stays a split and its parts are untouched.
Editing a Rule as JSON#
Every rule can be edited as raw JSON instead of clicking through the visual builder — useful for power users who prefer to type, and for copying a rule between instances.
At the top of the rule editor, switch from Builder to JSON. The current rule is shown as an editable JSON document (its criteria, actions, and settings). Edit it freely, or paste a rule copied from elsewhere, then:
- Save — the JSON is checked when you save; if the structure is wrong (an unknown field, an invalid match type, a missing category) the error is shown so you can fix it. Switching back to Builder first re-parses the JSON and repopulates the visual widgets, which is a quick way to sanity-check it.
- Copy JSON — copies the document to your clipboard so you can share a rule or move it to another Budget instance.
Note: Category and account IDs in the JSON are specific to the instance the rule came from. When you paste a rule into a different instance, point those IDs at the matching categories/accounts there (or set them in the Builder afterwards).
Exporting and importing all rules#
The Export button at the top of the Rules page downloads all your rules as a single JSON file (budget-rules-<date>.json) — a quick backup, or a way to move your whole rule set elsewhere. Rules shared with you by others are not included (they belong to their owner). Your rules are also included automatically in a full data export if you'd rather move everything at once.
The Import button reads such a file back in and creates the rules. It accepts an exported file or a bare list of rules. A rule that references a category or account which doesn't exist on this instance is rejected and reported (so nothing is silently mis-filed) — after importing, fix those references in the Builder or JSON editor. Import adds rules; it never overwrites or removes existing ones, so re-importing the same file makes duplicates.
Sharing Rules#
Rules can be shared with other Nextcloud users you already share your budget with. In the Sharing page, open a share's Configure panel and pick which rules to share, at read-only or read/write permission.
A rule shared with you shows a "Shared" badge on the Rules page. You can run it, and with write permission edit it (edits affect the owner and every recipient — it's one rule, not a copy); only the owner can delete it. Shared rules also run during your own imports. See Sharing for how a shared rule's set category / set account actions behave for the recipient.
Related Features#
- Import — rules are applied automatically during the import process
- Transactions — rules modify transaction fields
- Categories — the most common rule action is setting a category
- Tags — rules can add global tags and category tags
Settings#
- Auto-apply import rules — sets whether the Apply import rules for categorization box on the import screen starts ticked for each new file (see Import). When the box is unticked, the rules are left out of that import and you can run them afterwards with Apply Rules.