Build condition-based rules that automatically categorize, tag, and annotate transactions at sync time using Breadbox’s recursive AND/OR/NOT rule engine.
Breadbox’s rules engine lets you define conditions that run automatically whenever transactions are synced. When a transaction matches a rule’s conditions, the rule assigns a category, adds tags, or leaves a comment — without any manual intervention. This is one of Breadbox’s most powerful features for keeping your transaction history organized.
A rule is a JSON document that pairs a condition (which transactions to match) with one or more actions (what to do with them). Rules run at sync time in a defined pipeline order. You can also apply rules retroactively to your full transaction history at any time.A single rule can:
Set a transaction’s category (set_category)
Add a tag to the transaction (add_tag)
Remove a tag from the transaction (remove_tag)
Leave an automated comment explaining the categorization (add_comment)
Provider’s raw primary category (does not change when Breadbox reassigns)
category_detailed
string
Provider’s raw detailed subcategory
category
string
Currently assigned Breadbox category slug (updates mid-pipeline as rules run)
pending
boolean
Whether the transaction is pending
provider
string
plaid, teller, or csv
account_id
string
Account UUID
account_name
string
Account display name
user_id
string
Family member UUID
user_name
string
Family member display name
tags
tags
Current tag slugs on the transaction
Use category (not category_primary or category_detailed) when you want a condition to react to the category that Breadbox or a prior rule assigned. The category_primary and category_detailed fields always hold the provider’s original values and never change.
Rules run in pipeline order — lower stage numbers run first. For set_category, the last matching rule wins, so higher-stage rules have the final say on categorization. For add_tag and add_comment, every matching rule contributes.
Stage name
Priority
Purpose
baseline
0
Foundation rules — broad, default classifications
standard
10
General-purpose rules (default when no stage is specified)
refinement
50
Reacts to output from baseline and standard rules
override
100
Has the final say — overrides everything below
Supply stage as a string in the request body. You can also supply a raw priority integer (0–1000) for fine-grained ordering within a stage. If you supply both, priority wins.
Because rules run in pipeline order and share a mutable transaction context, later rules can react to what earlier rules did. A rule that assigns a category at stage 0 makes that category readable via field: "category" for any rule at stage 10 or higher in the same sync pass.
A rule with no trigger specified defaults to on_create, which means it fires only on newly synced transactions. Use always to also run on re-synced changes, or on_change to run only when an existing transaction is modified.
The response returns a match count and a sample of matched transactions. Preview evaluates the condition in isolation — it does not simulate the full pipeline.
After creating or editing a rule, apply it to your full transaction history without waiting for the next sync:
curl -X POST \ -H "X-API-Key: bb_your_key" \ http://localhost:8080/api/v1/rules/rule_abc123/apply
Retroactive apply respects the same pipeline stage ordering as sync. It also respects category_override — transactions with a manual override are skipped for set_category actions, just as they are during sync.
add_comment actions do not fire during retroactive apply. Comments are designed to narrate a specific sync event and are only written during live syncs.
If a transaction has been manually categorized (its category_override flag is true), a rule’s set_category action is skipped for that transaction. The rule still runs — add_tag and add_comment actions fire normally — but the category is not changed. This means you can safely apply rules in bulk without worrying about undoing deliberate manual work.
