What a transaction enrichment API should return on a miss.

A miss is a normal bounded outcome, not an excuse to guess. When a descriptor yields a readable merchant phrase but no reviewed merchant match, the API should return the evidence it has, identify the uncertainty, and omit metadata it cannot support.

NORTHSIDE MARKET 017 KINGSTON

The implemented parser removes the numeric reference token and returns “Northside Market Kingston” as a useful fallback. It should not invent a domain, select a similarly named chain, or attach a logo merely to make the response look complete.

A bounded miss response

{
  "normalized_merchant": "northside market kingston",
  "display_name": "Northside Market Kingston",
  "category": null,
  "subcategory": null,
  "website": null,
  "logos": {
    "preferred": null,
    "variants": [],
    "warnings": ["no_verified_logo_for_local_merchant"]
  },
  "confidence": 0.56,
  "recurring_hint": false,
  "processor_hint": "unknown",
  "location_hint": null,
  "signals": ["removed_reference_tokens"],
  "warnings": ["local_merchant_identity_not_verified"]
}

The response stays useful to client UI: show the fallback label, choose a neutral icon, and keep edit or feedback controls available. The warning explains why richer fields are absent. Confidence helps the client choose a presentation policy, but the warning remains important because a decimal score alone does not explain the limitation.

TxnKit may record privacy-safe miss evidence for later offline review. That internal follow-up does not delay the online response and does not turn the request path into live research. See confidence scores and warnings for client-side handling patterns.

When to use it

Use a bounded miss response when transaction rows must remain readable even when merchant coverage is incomplete. It fits budgeting, expense, accounting-import, loyalty, and personal-finance interfaces that can render honest fallback states.

When not to use it

Do not use a low-confidence fallback as proof of legal merchant identity, tax treatment, sanctions status, fraud attribution, chargeback evidence, or rewards settlement. Those decisions require evidence and workflows beyond descriptor cleanup.

Privacy caveat

A cache miss must not become a privacy leak. Keep card numbers, account numbers, customer PII, bank credentials, emails, phone numbers, addresses, and full statements out of requests, logs, cache keys, and offline review records. Store only bounded, privacy-safe evidence needed to improve reviewed coverage.