Merchant Intelligence

The merchant text printed on receipts is messy — abbreviations, store codes, franchise variations. Merchant Intelligence turns it into clean, verified merchant data: standardised names, enriched addresses, and location matching against your own list of known merchants. It's the difference between "MCD #4471 QPS" and a verified McDonald's at a specific address.

Availability

📘
Availability
This feature is included on the Startup plan and above. Enable Normalised Merchant Location in your account Feature Settings when the control is available. See Plans & Feature Access.

Location Matching & Verification

Identifies and verifies the merchant location on a receipt against a list of known merchants you provide. Built for cases where where the purchase happened matters — such as mall loyalty programs where rewards only apply to stores inside the mall.

How It Works

Extraction: address information is extracted from the receipt or invoice.
Geocoding: the address is converted into geographical coordinates.
Matching: the location is matched against your imported list of known merchant locations, using fuzzy name matching and geographic distance.
Verification: the match is confirmed only if the merchant name matches and the receipt's address is within 25 km of an entry on your list.

You can also pass a near hint on any extraction request to help locate the merchant when you already know the user's city or region.

Setting Up Your Known-Merchants List

Import your merchants as a CSV or TSV file with Upload Known Merchants, then review the stored list with Export Known Merchants.

CSV/TSV columns

Column	Required	Purpose
`merchantName`	Yes	The only column needed for name matching.
`merchantAddress`	For location matching	Street address.
`merchantCity`	For location matching
`merchantState`	For location matching
`merchantPostalCode`	For location matching
`merchantCountryCode`	For location matching	Two-letter country code.
`merchantCoordinates.x`	Recommended for large lists	Longitude.
`merchantCoordinates.y`	Recommended for large lists	Latitude.
`locationId`	Optional	Your own store or location ID. When a receipt matches this location, Taggun returns it as `locationId` in the response (see the table below).

Name matching needs only merchantName. Location matching needs address fields, coordinates, or both.

👍
Supply coordinates for large lists
When you include ArcGIS-compatible merchantCoordinates.x (longitude) and .y (latitude), Taggun uses them directly. When coordinates are missing, Taggun calculates them from the address during import; this can take a long time for large lists. All imports follow the same processing path—first imports are not inherently slower. Supplying coordinates keeps large imports faster.

Two things to keep in mind:

Each import replaces your entire stored list. Always upload the complete current list, not a delta — stores missing from the list won't match even when the location is right.
For a large known-merchants list, contact support so the team can validate current import and matching performance for your volume. No public hard ceiling or guaranteed count threshold is documented.

Response

entities.normalisedMerchant, its data object, and the individual match and location properties are optional and may be omitted. A returned locationId envelope may be null, and its data value may be omitted or null. Treat a missing or unusable value as no documented match result returned, not as a successful match. The root merchantName and merchantAddress envelopes are optional. They may be omitted, empty, or present without usable data. Guard each envelope and its data leaf before use.

Field	Type	Access Path	Description
Merchant name matched?	Boolean	`entities.normalisedMerchant.data.isMerchantNameMatched`	`true` if the detected merchant name is on your list — even if this particular store is at another location.
Merchant address matched?	Boolean	`entities.normalisedMerchant.data.isMerchantAddressMatched`	`true` only when the name matches AND the location corresponds to a store on your list. A store missing from your list returns `false` even on a perfect location match.
Location ID	String	`entities.normalisedMerchant.data.locationId.data`	Your identifier for the matched location, from the imported list.
Location ID confidence	Number	`entities.normalisedMerchant.data.locationId.confidenceLevel`	Field-specific distance signal when the address matches: `0.99` under 1 km, decreasing linearly to `0.5` at 25 km. This is not the overall document confidence; do not apply the overall `<0.8` review threshold to it.
Merchant name	optional string	`merchantName.data`	The standardised merchant name.
Merchant address	optional string	`merchantAddress.data`	The merchant address — enriched, not just what's printed on the receipt.

{
  "entities": {
    "normalisedMerchant": {
      "data": {
        "isMerchantNameMatched": true,
        "isMerchantAddressMatched": true,
        "locationId": {
          "data": "location_id",
          "confidenceLevel": 0.85
        }
      }
    }
  },
  "merchantName": { "data": "Normalised Merchant Name" },
  "merchantAddress": {
    "data": "123 Main Street, City, State, 12345",
    "confidenceLevel": 0.85
  }
}

Use Cases

Shopping-mall loyalty programs: rewards apply only to specific store locations, not other branches of the same brand — see Receipt Validation for the full campaign workflow.
Fraud detection: flag purchases from unusual or out-of-scope locations.
Consistent reporting: when a usable normalised merchant match is returned, use the returned standardised name to improve consistency across receipt formats and branches.

Best Practices

Use the matched flags to gate decisions.
Keep your merchant list current — matching is only as good as the list.
List merchant names as they're printed on receipts. Display-style names ("Store Name – Downtown Mall") and legal suffixes the receipt doesn't show hurt matching.
Verify coordinates when you import; bad geocoding on your side produces false negatives.

Need something not covered here? Contact [email protected] — see Contacting Support.