Merchant Data Model#

The merchants table uses Single Table Inheritance (STI) to store two distinct merchant subtypes under one table, distinguished by a type column 1. The two concrete classes are:

• FamilyMerchant — user-created merchants scoped to a specific Family 2
• ProviderMerchant — globally shared merchants sourced from external data providers 3

The type column and STI structure were added in a 2025 migration that also made family_id nullable and introduced website_url, logo_url, and source columns 4.

Base class: Merchant#

app/models/merchant.rb defines the shared interface:

• has_many :transactions, dependent: :nullify — deleting a merchant nullifies the FK on transactions, not the transactions themselves 5
• has_many :recurring_transactions, dependent: :destroy 6
• Validates name presence and type inclusion in TYPES = %w[FamilyMerchant ProviderMerchant] 7
• Scope: alphabetically orders by name 8

FamilyMerchant#

app/models/family_merchant.rb — private, per-family merchants:

• belongs_to :family — name uniqueness is enforced within a family's scope 9 10
• Auto-assigns a random display color from a 10-color palette on creation 11 12
• Auto-generates logo_url from website_url via the BrandFetch CDN when the URL is set or changes, gated on Setting.brand_fetch_client_id 13 14
• Destroying a FamilyMerchant deletes the record entirely 15

ProviderMerchant#

app/models/provider_merchant.rb — globally shared merchants synced from financial data providers:

• source enum covers 14 providers: plaid, simplefin, lunchflow, akahu, up, synth, ai, enable_banking, coinstats, mercury, brex, indexa_capital, sophtron, questrade 16
• Name uniqueness is scoped to source — the same merchant name can exist across different providers 17
• Cannot be deleted via the UI — instead, unlink_from_family nullifies merchant_id on the family's transactions and records the event in FamilyMerchantAssociation 18
• Conversion: convert_to_family_merchant_for(family, attributes) creates a new FamilyMerchant for the family and re-points all that family's transactions to it. It also calls Entry.mark_user_modified_for_transactions! first, to protect the reassignment from being reverted by the next provider sync 19

FamilyMerchantAssociation#

A join/tracking table created in a 2026 migration 20. Records when a ProviderMerchant was last unlinked from a family (unlinked_at). Used by the UI to surface "recently unlinked" merchants within the past 30 days 21.

Rules Integration#

Merchants participate in the transaction rules engine via two classes under app/models/rule/:

The condition filter uses left_joins(:merchant) and filters on merchants.id 22. The action executor resolves the target merchant from the family's own merchants and calls enrich_attribute(:merchant_id, ...) with source: "rule", respecting attribute locks unless overridden 23.

Key Entry Points#