Merchant Data Enhancement#

Overview#

Merchant data enhancement is the process of enriching ProviderMerchant and FamilyMerchant records with website_url and logo_url fields. The two merchant subtypes use fundamentally different enrichment mechanisms: ProviderMerchant relies on an LLM pipeline triggered as an async job, while FamilyMerchant uses an automatic before_save callback that fires whenever a website URL is set.

ProviderMerchant: LLM-based Enrichment#

Pipeline Entry Point#

Enhancement is triggered via EnhanceProviderMerchantsJob, a medium_priority background job that accepts a family and calls ProviderMerchant::Enhancer.new(family).enhance 1. A cache key (enhance_provider_merchants:{family.id}) is cleared in an ensure block to prevent duplicate runs 2.

Enhancer Logic#

ProviderMerchant::Enhancer orchestrates the full pipeline:

1. Target selection — fetches all ProviderMerchant records assigned to the family where website_url is blank 3.
2. LLM call — sends merchants to Provider::Registry.preferred_llm_provider in batches of 25 via enhance_provider_merchants(merchants:, family:) . Both Provider::Anthropic and Provider::OpenAI implement this method with provider-specific strategies (tool-use vs. JSON schema).
3. Update — for each merchant that the LLM returns a business_url for, website_url is written immediately. logo_url is also set via build_logo_url if Setting.brand_fetch_client_id is present 5.
4. Deduplication — any other ProviderMerchant assigned to the family that shares the same website_url is treated as a duplicate: the family's transactions are re-pointed to the winning merchant 6. FamilyMerchant records are explicitly excluded from deduplication 7.

On-demand Logo Regeneration#

If a ProviderMerchant's website_url is manually corrected after the fact, generate_logo_url_from_website! can be called directly to rebuild the Brandfetch CDN URL. If website_url is blank, the method sets logo_url to nil 8.

FamilyMerchant: Automatic Callback Enrichment#

FamilyMerchant has no LLM step. Logo enrichment is handled entirely by a before_save callback: generate_logo_url_from_website runs whenever should_generate_logo? returns true — i.e., whenever website_url changes or website_url is present but logo_url is blank 9.

The callback builds the same Brandfetch CDN URL format as the ProviderMerchant pipeline, gated on Setting.brand_fetch_client_id 10. If website_url is cleared, logo_url is set to nil 11.

Because FamilyMerchant has no LLM pipeline, website_url must be supplied by the user (or copied from a ProviderMerchant during conversion). There is no automatic discovery of URLs for family-specific merchants.

Coverage Gap#

The practical consequence: ProviderMerchant records created without a website_url will remain logo-less until the enhancement job runs (and until the LLM can identify the business URL). FamilyMerchant records get logos automatically the moment website_url is written, but only if the user provides the URL in the first place.

Domain Extraction#

Both types strip the www. prefix before constructing CDN URLs. ProviderMerchant does this inside Enhancer#extract_domain 12 and the instance method extract_domain on the model 13. FamilyMerchant has its own identical private extract_domain 14.

Key Files#

See also: Merchant Data Model article (STI structure and relationships), Brandfetch Logo Integration article (CDN URL format and client ID configuration).