> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant matching guide

***

<Info>
  Merchant matching is not enabled by default. To request access, please contact us at [sales@spade.com](mailto:sales@spade.com)
</Info>

## Overview

Merchant matching lets you search our database and retrieve location and counterparty IDs, powering merchant attribution and rewards use-cases.

You can call the merchant matching endpoint ahead of enrichment time with a merchant name and address, mapping an in-house merchant entry to a Spade counterparty and location ID. Then, when you call the real-time enrichment API, you can compare the IDs in the transaction object to the ones in your database -- instantly recognizing which merchant and location the transaction has occurred at.

Merchant matching can be done in batch or real-time:

* Real-time merchant matching: send single merchant name and location pairs, and receive Spade location and counterparty ID instantly. To learn more, see our [real-time merchant matching guide](/reference/real-time-merchant-matching-guide).
* Batch merchant matching: send batches of up to 50,000 merchant name and location pairs at once for mass matching. Results can be retrieved through webhooks or endpoint polling. To learn more, see our [batch merchant matching guide](/reference/batch-merchant-matching-guide).

## Why use merchant matching?

| Challenge                                                                                                                                                                   | How merchant matching helps solve                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Raw merchant data from partners is inconsistent, making it hard to normalize -- e.g., “Amazon”, “Amazon #1234”, and “AMAZON.COM 800‑123‑4567” may refer to the same entity. | Merchant matching normalizes every record to a single counterparty and location ID.                                                                          |
| Name‑only matching leads to false positives (e.g., “Sweetgreen” vs. “Sweetgreens Café”).                                                                                    | Spade scores every match (0–100). You choose your own similarity threshold.                                                                                  |
| Enrichment APIs require an online call for every transaction.                                                                                                               | Merchant matching is offline & one‑time. Once you store the Counterparty/Location IDs, you can identify them in every future transaction response instantly. |