Merchant search is not enabled by default. To request access, please contact us at sales@spade.com
Overview
Merchant search allows you to query Spade’s database for detailed merchant information. Using merchant search, you can discover a merchant’s counterparty ID, MCCs, Spade industries, affiliated businesses, and more. With this information, you can create rules and confidently make critical transaction authorization decisions.Searching for a merchant
You can use merchant search to retrieve detailed information about a merchant. Let’s try sending the following request to the/merchants
endpoint.
Note that the old/merchants/advanced
endpoint is now deprecated. All of this endpoint’s functionality is now available at/merchants
.
similarity
to the search query. Up to five counterparties and third parties will be returned. In the next section, we’ll discuss the data included in merchant search results in detail.
Understanding merchant search results
In merchant search, merchant results will be returned as counterparties, third parties, or both based on how they appear in enrichments. For more information on the difference between counterparties and third parties, see our Glossary.Third Party Information
- Third party results contain all the information you would find on a third party returned in an enrichment. This includes id, name, type, logo, website, and similarity, where similarity is a value between 0 and 100 indicating the relevance of the third party to the merchant search query.
Counterparty Information
- Similar to third party results, counterparty results include ids, names, logos, websites, and similarities along with some important, more granular, attributes.
- Affiliates: Affiliates are other merchants which Spade believes have a relationship to a counterparty. Take Valero and Circle K, or Dunkin and Baskin-Robbins — businesses which are often located in the same physical space. You might be interested in creating spending controls that allow transactions at both merchants to be processed, while preventing transactions at other businesses. You can use a counterparty’s
affiliates
to make decisions about transactions occurring at related merchants. Each affiliate includes its id, name, logo and website. - Alternates: Alternates are IDs that have a very low (often less than 1%) chance of being returned during a transaction enrichment at the corresponding counterparty. Along with the ID, we provide a
similarity
score which reflects this ID’s likeness to the counterparty. Results are limited to five alternate counterparties. You can use these alternate IDs to dramatically reduce false declines resulting in rules based on counterpartyIDs. - Spade Categories: Each counterparty includes
expectedSpadeCategories
. These are our proprietary categories which appear in enrichments. We analyze our data to determine which Spade Categories are most likely to appear on transactions processed by each merchant. Each Spade Category also includes a list of all its ancestor categories in the fullfullCategoryHierarchy
object. Ancestor categories are more broad than their specific children. Note that a merchant’sexpectedSpadeCategories
may change over time as we continue to refine our understanding of what goods and services that merchant provides. - Merchant Category Codes: Specified by ISO 18245, Merchant Category Codes are widely used to classify the kinds of products or services provided by a business. We derive
expectedMerchantCategoryCodes
from our data and include those which are most likely to appear in a merchant’s transactions. Each MCC includes its code and description. Similarly toexpectedSpadeCategories
, MCCs may change over time as we continue to improve our data.
Integrating merchant search into your application

Step 1: Set up a proxy endpoint on your backend
For security reasons, you’ll first need to set up an endpoint on your backend to act as a middleman between your frontend and Spade’s API. Here’s how you might set up this endpoint using Flask:Step 2: Add the autocomplete input to your frontend
Now that you have an endpoint to hit, you can add an autocomplete input to your frontend to allow your users to search Spade’s merchant database. Many frameworks and packages provide autocomplete functionality out of the box. Here’s an example written in Svelte using thesimple-svelte-autocomplete
package:
Depending on your tech stack, you may need to throttle / debounce requests manually. Because Spade’s merchant merchant search API is rate-limited, it is important that you throttle / debounce requests in order to avoid making too many requests.If your existing tech stack doesn’t provide a function to throttle / debounce requests,
lodash
is a relatively lightweight package that provides simple functions for throttling and debouncing.