Transaction categorization

Categorize, match, uncategorize, and manage rules for bank transactions.

Layer MCP can retrieve and act on bank transactions for the configured business. Matching and categorizing are different actions: match confirms a suggested invoice/bill (or other) match; categorize assigns a ledger account, split, or exclusion.

Amounts are integer cents. For REST request shapes, see Transaction categorization, Categorize Bank Transaction, Match Bank Transaction, and Bulk Match or Categorize.

Sequence

1. List transactions that need review

   Call always-load get_bank_transactions with filters (date range, direction, amount, categorization status, description, merchant, customer, vendor, external account, tags, search). Use cursor / limit on lists. Fetch one row with get_bank_transaction.

2. Load valid accounts

   Call always-load get_chart_of_accounts before categorizing so account IDs and stable names are valid.

3. Match or categorize

   Use match_bank_transaction when the transaction already has a suggested match to confirm. Use categorize_bank_transaction to assign a single account, split across accounts, or exclude. Use bulk_match_or_categorize_bank_transactions for a map of transaction id → match or categorize.

4. Undo or annotate when needed

   uncategorize_bank_transaction and bulk_uncategorize_bank_transactions are destructive. update_bank_transaction_metadata updates memo-style fields without changing categorization.

Reads (core + accounting)

Always-load on business: get_bank_transactions. Also: get_bank_transaction, get_chart_of_accounts (always-load).

get_bank_transactions is available in platform and business mode. Categorize/match/uncategorize writes are business only (core + accounting, except bulk categorize which is accounting).

Categorize vs match vs uncategorize

Tool	What it does
categorize_bank_transaction	Always-load on business. Single account, split, or exclude. Distinct from match.
match_bank_transaction	Confirms a suggested match. Does not assign a P&L category.
bulk_match_or_categorize_bank_transactions	Map of transaction id → match or categorize.
uncategorize_bank_transaction / bulk_uncategorize_bank_transactions	Destructive. Clears categorization.
update_bank_transaction_metadata	Metadata only.

Splits must sum to the transaction amount. See Split Categorizations.

Search phrases: match vs categorize, confirm suggested match, assign ledger account, exclude.

Rules and suggestions

Business writes in accounting:

• list_categorization_rules, get_categorization_rule
• create_categorization_rule, update_categorization_rule
• archive_categorization_rule (destructive)
• list_categorization_rule_suggestions
• accept_categorization_rule_suggestion
• reject_categorization_rule_suggestion (destructive)

See Categorization rule suggestions.

Related workflows

• Attach receipts with Receipts (prepare → S3 PUT → complete; never base64 through the model).
• Dimension tags with Tags and journal entries. Tag filters on bank transaction list are supported; report tag filters are limited (see Financial reports).