Creating a custom matching rule

When to create a rule

The default matching pipeline (how the matching pipeline works) handles 90% of cases automatically. Rules are for the remaining 10% — patterns that recur predictably and that the default scoring doesn't quite catch, or that you want to short-circuit with a fixed outcome.

Typical reasons to create a rule:

• A specific vendor's bank counterparty name doesn't match their TaxItEasy vendor name, so counterparty scoring is weak.
• You want to auto-categorise certain transactions (Stripe payouts → "Revenue: Stripe", AWS → "Infrastructure") without manually picking the category each time.
• You want to ignore certain transactions entirely (internal transfers between your own accounts, your salary draw, etc.) so they stop cluttering the suggestion inbox.
• You have a recurring invoice and want each cycle's payment to auto-match it without going through the 70-point threshold.

Rules are a power-user feature. If you're handling under 50 transactions/month, you might never need one — the defaults will do.

Who can create rules

Custom matching rules are role-gated: Owner / Admin / Bookkeeper. Members and Viewers cannot create rules. They can still benefit from rules others have created — the rule fires regardless of who triggered the matching event.

The feature is available on every plan (Free / Starter / Business / Growth) with no tier-gate. The role-gate is the only access constraint. See companies, users, and roles for the role hierarchy.

The role-gate exists because rules can change the categorisation of large amounts of data; misconfigured rules can corrupt your books. Members and Viewers don't have edit access on invoices, so it's consistent to keep them out of rule creation too.

The walk-through

Step 1 — open the rules page

Settings → Matching rules. The page lists existing rules in priority order, with their conditions and actions visible inline. Each rule shows: name, priority, status (active / inactive), last-fired timestamp, total times fired.

Step 2 — create a new rule

Click New rule. The rule editor opens with empty condition and action fields.

Give the rule a memorable name. Names show up in the audit log every time the rule fires (Matched by rule: AWS infra → Infrastructure), so something descriptive helps you trace back later. Examples: Stripe payouts → Revenue:Stripe, AWS hosting → Infra, Ignore internal transfers.

Step 3 — define the condition

Conditions can match against:

• counterparty — the bank counterparty name (the human-readable name the bank shows)
• counterparty IBAN — the IBAN if your bank provides it
• description / bank reference — the reference text
• amount — exact, or in a range
• currency — for multi-currency accounts
• category (set by a prior rule) — useful for chaining

Operators per field:

• Text: contains, equals, starts with, ends with, does not contain
• Number: =, ≠, <, ≤, >, ≥, between X and Y
• IBAN: equals (exact match — IBANs are normalised internally so spacing variants match)

Combine with AND / OR for multi-clause conditions. For example: counterparty contains "AWS" AND amount > 100 matches AWS transactions over €100; counterparty contains "AWS" OR counterparty contains "Amazon Web" matches either name variant.

Step 4 — define the action

Three action types:

• Assign category — sets the expense category on the matched invoice (or directly on the transaction if no invoice is matched). The category dropdown shows your existing categories; you can create new ones inline.
• Auto-match to recurring invoice — if you have a recurring invoice in your books (e.g. a monthly hosting subscription that you've marked as recurring — see recurring vendor patterns), this action links the matching transaction directly to the next open cycle of that recurring invoice. Bypasses the scoring pipeline.
• Ignore — for transactions you never want to see (internal transfers between your own bank accounts, owner draws, automatic FX transfers). The transaction is marked as "matched (ignored)" and disappears from the suggestion inbox.

You can also combine actions on chained rules (one rule assigns category, a subsequent lower-priority rule auto-matches).

Step 5 — set priority

Rules are evaluated top-down. Priority is a small integer (lower = higher priority); the first rule whose condition matches a transaction fires, and subsequent rules are not evaluated for that transaction.

When you have multiple rules:

• Specific rules (narrow conditions) get high priority.
• General rules (broad conditions) get low priority.
• Ignore rules typically get the highest priority so they run before category-assignment rules.

Example priority order: 1 → Ignore internal transfers, 2 → Stripe payouts, 3 → AWS infra, 4 → Catch-all under €50 → Misc.

Step 6 — save and apply

Save activates the rule for all future transactions. To also apply it to past transactions:

• Open the rule detail page.
• Click Apply to past transactions.
• Confirm the scope (last 30 days / 90 days / since 2026 / all time).
• The rule runs against historical transactions in batch. Rules don't overwrite manual edits — only transactions where the relevant field is still empty are affected.

The backfill respects audit-trail: every retroactively-applied rule action is recorded with applied_at: <retroactive date> so you can distinguish forward-applied rules from backfill.

Example rules that pay off quickly

A few that real users have created (anonymised):

• Stripe payouts: counterparty contains "Stripe" → category "Revenue: Stripe". Saves a click on every Stripe payment.
• AWS / Adobe / Microsoft / Google Workspace infra rules: counterparty contains "AWS" OR contains "Amazon Web" → category "Infrastructure". Same for the other SaaS vendors. Most teams set up 5–10 of these.
• Internal transfer ignore: counterparty IBAN equals <your other account's IBAN> → action Ignore. Keeps reconciliation cleaner; transfers between your own accounts aren't business transactions.
• Owner draw ignore (for sole proprietors): counterparty contains <your own name> AND amount > 1000 → Ignore. Same idea — owner draws aren't business expenses.
• Small payments auto-categorise: amount < 5 AND amount > 0 → category "Bank fees". Tiny payments are usually FX margins or bank fees.

The rules that pay off best are usually the ones that handle 50+ transactions/month. A rule that fires twice doesn't earn back its setup cost.

What rules can't do

• Override the AI's vendor extraction on documents. That's a different surface — see how to fix a misread vendor name.
• Create invoices from transactions. Rules only act on existing transactions; they don't synthesise invoices.
• Bypass per-company scoping. Rules are per-company. If you run multiple companies, each has its own rule set.
• Run on documents (PDFs, receipts). Rules act on bank transactions, not on extracted documents. Document-side categorisation comes from the AI's Suggested category, plus your per-vendor overrides.

Troubleshooting

My rule matches but the wrong category gets applied. Check priority: a higher-priority rule (lower number) is firing first. Lower the priority of the unwanted rule, or refine its condition to exclude the transactions you want the second rule to catch.

I want to disable a rule temporarily without deleting it. Open the rule; toggle the Active switch. Inactive rules don't fire but stay configured for later. Useful for seasonal rules (e.g. an end-of-year tax-categorisation rule you re-activate in Q4).

Rule fired on past transactions I'd already categorised manually. Rules don't overwrite your manual categorisations. They only fire on transactions where the category field is still empty (or whichever target field the rule is acting on). If you're seeing overwrites, write to [email protected] with the rule ID and the affected transaction ID.

Can I see which rule caused which match? Yes — on the transaction detail page, the matched-by source shows e.g. "Rule: AWS infra" instead of "Auto-match: score 87". The audit log records the rule name and version each time it fires.

I exported and re-imported a CSV; my rules ran again on the same transactions. Re-imports detect duplicate transactions by unique ID (statement reference + amount + date hash). If the duplicate is recognised, no re-rule-firing. If your CSV format doesn't include a stable transaction ID, you might be importing them as fresh transactions — in which case rules do fire again. Use the bank-CSV format from your bank rather than a manually-edited copy where the IDs might be missing.

My rule with counterparty IBAN equals X isn't firing even though the IBAN matches. Check that IBAN normalisation is on (it is by default — spaces stripped, uppercased). If your CSV has IBANs with non-standard formatting (BIC mixed in, country code missing), pre-process the CSV before import or use the regular counterparty-name condition instead.

Rules limit? No hard cap. You can create as many as you need. The evaluation cost per transaction grows linearly with rule count; most teams stay well under 50 rules without performance impact.

Related

• How the matching pipeline works — what rules sit on top of
• Recurring vendor patterns — recurring is one of the rule actions
• Companies, users, and roles — the Bookkeeper+ role gate