Merchant search guide

Category personalization is not enabled by default. To request access, please contact us at [email protected].

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.

import requests

response = requests.get("https://east.sandbox.spade.com/merchants", params={"name": "walmart"}, headers={"X-Api-Key": "<Your API Key Here>"})
results = response.json()

print(results)

And here's the response we get from this query.

{
  "counterparties": [
    {
      "id": "d730906b-f1a8-49f1-9939-f27390170a6d",
      "name": "Walmart",
      "similarity": 100.0,
      "logo": "https://static.v2.spadeapi.com/logos/d730906bf1a849f19939f27390170a6d/light.png",
      "website": "walmart.com",
      "affiliates": [
        {
          "id": "63fd64b8-8d35-44b1-8aef-324a8a1b279c",
          "name": "Sam's Club",
          "logo": "https://static.v2.spadeapi.com/logos/63fd64b88d3544b18aef324a8a1b279c/light.png",
          "website": "samsclub.com"
        }
      ],
      "alternates": [
        {
          "id": "6b4e8b7b-d5dd-37cf-afdf-00d05fe314d2",
          "similarity": 0.89
        },
        {
          "id": "28f1c5bd-1785-3b78-bc70-0a42fa6c04aa",
          "similarity": 0.89
        },
        {
          "id": "1c735755-fa71-38ff-aea0-ea9b19247a87",
          "similarity": 0.89
        },
        {
          "id": "41ccc32d-22db-3ccc-8403-a9e169d58a7d",
          "similarity": 0.89
        },
        {
          "id": "92102ff2-fe2d-32bb-a59f-215d4b9c1923",
          "similarity": 0.89
        }
      ],
      "expectedSpadeCategories": [
        {
          "id": "011-014-000-000",
          "name": "Supermarkets and Grocery Stores",
          "icon": "https://static.v2.spadeapi.com/categories/4d937d51e9cd44a0bbed1621363158c2/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "011-000-000-000",
              "name": "Retail",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-014-000-000",
              "name": "Supermarkets and Grocery Stores",
              "icon": "https://static.v2.spadeapi.com/categories/4d937d51e9cd44a0bbed1621363158c2/light.png"
            }
          ]
        },
        {
          "id": "011-006-000-000",
          "name": "Gas Stations",
          "icon": "https://static.v2.spadeapi.com/categories/fac7777cc0044a25a175f264252fd762/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "011-000-000-000",
              "name": "Retail",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-006-000-000",
              "name": "Gas Stations",
              "icon": "https://static.v2.spadeapi.com/categories/fac7777cc0044a25a175f264252fd762/light.png"
            }
          ]
        },
        {
          "id": "011-016-000-000",
          "name": "Warehouses and Wholesale Stores",
          "icon": "https://static.v2.spadeapi.com/categories/06e495ee6c06413988e510e0c581b80b/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "011-000-000-000",
              "name": "Retail",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-016-000-000",
              "name": "Warehouses and Wholesale Stores",
              "icon": "https://static.v2.spadeapi.com/categories/06e495ee6c06413988e510e0c581b80b/light.png"
            }
          ]
        },
        {
          "id": "011-018-003-000",
          "name": "Discount Stores",
          "icon": "https://static.v2.spadeapi.com/categories/3fa31bce80a04ff99ec2762a8c47f22d/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "011-000-000-000",
              "name": "Retail",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-018-000-000",
              "name": "General Goods",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-018-003-000",
              "name": "Discount Stores",
              "icon": "https://static.v2.spadeapi.com/categories/3fa31bce80a04ff99ec2762a8c47f22d/light.png"
            }
          ]
        },
        {
          "id": "012-011-011-000",
          "name": "Optometrists",
          "icon": "https://static.v2.spadeapi.com/categories/8f0e090804e54b01b72388be693e8a28/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "012-000-000-000",
              "name": "Services",
              "icon": "https://static.v2.spadeapi.com/categories/922d5d4ec3a64304a93723bea02d3890/light.png"
            },
            {
              "id": "012-011-000-000",
              "name": "Medical and Healthcare Services",
              "icon": "https://static.v2.spadeapi.com/categories/8f0e090804e54b01b72388be693e8a28/light.png"
            },
            {
              "id": "012-011-011-000",
              "name": "Optometrists",
              "icon": "https://static.v2.spadeapi.com/categories/8f0e090804e54b01b72388be693e8a28/light.png"
            }
          ]
        },
        {
          "id": "011-018-002-000",
          "name": "Department Stores",
          "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "011-000-000-000",
              "name": "Retail",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-018-000-000",
              "name": "General Goods",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            },
            {
              "id": "011-018-002-000",
              "name": "Department Stores",
              "icon": "https://static.v2.spadeapi.com/categories/ee4ee39fd5474d31ac42f9e606b9040a/light.png"
            }
          ]
        },
        {
          "id": "005-005-000-000",
          "name": "Food Delivery Services",
          "icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png",
          "fullCategoryHierarchy": [
            {
              "id": "005-000-000-000",
              "name": "Food and Drink",
              "icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png"
            },
            {
              "id": "005-005-000-000",
              "name": "Food Delivery Services",
              "icon": "https://static.v2.spadeapi.com/categories/18785677534e4e3a8ec37e4dc7dc34d9/light.png"
            }
          ]
        }
      ],
      "expectedMerchantCategoryCodes": [
        {
          "code": "5411",
          "description": "Grocery Stores, Supermarkets"
        },
        {
          "code": "5541",
          "description": "Service Stations ( with or without ancillary services)"
        },
        {
          "code": "5300",
          "description": "Wholesale Clubs"
        },
        {
          "code": "5310",
          "description": "Discount Stores"
        },
        {
          "code": "8043",
          "description": "Opticians, Opticians Goods and Eyeglasses"
        },
        {
          "code": "5968",
          "description": "Direct Marketing – Continuity/Subscription Merchant"
        },
        {
          "code": "5542",
          "description": "Automated Fuel Dispensers"
        },
        {
          "code": "5912",
          "description": "Drug Stores and Pharmacies"
        },
        {
          "code": "7392",
          "description": "Management, Consulting, and Public Relations Services"
        },
        {
          "code": "4814",
          "description": "Fax services, Telecommunication Services"
        },
        {
          "code": "5999",
          "description": "Miscellaneous and Specialty Retail Stores"
        },
        {
          "code": "5969",
          "description": "Direct Marketing – Not Elsewhere Classified"
        },
        {
          "code": "5311",
          "description": "Department Stores"
        },
        {
          "code": "8042",
          "description": "Optometrists and Ophthalmologists"
        },
        {
          "code": "5812",
          "description": "Eating places and Restaurants"
        },
        {
          "code": "7800",
          "description": "Government-Owned Lotteries"
        }
      ]
    }
  ],
  "thirdParties": []
}

Merchant search results are ordered by decreasing 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 full fullCategoryHierarchy object. Ancestor categories are more broad than their specific children. Note that a merchant's expectedSpadeCategories 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 to expectedSpadeCategories, MCCs may change over time as we continue to improve our data.

Integrating merchant search into your application

⚠
If you intend to integrate merchant search into your application and pass along results to your users, it's essential that you proxy merchant search requests through your backend to Spade's servers. Because client-side code is public and your API key is secret, you will need to proxy merchant search requests through your backend to Spade's servers.
⚠ NEVER send your API key to the client. This includes any client-side application code bundles (websites, mobile apps, etc...).

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:

from flask import Flask, request
from flask_login import login_required
import requests

app = Flask(__name__)
spade_api_key = os.environ.get("SPADE_API_KEY")

@app.get('/merchants')
# Make sure the user is authenticated. Only authenticated users should be able to query Spade's merchant database.
@login_required
def get_merchant_merchants():
    # Grab the name from the query parameters (i.e. GET /merchants?name=walmart)
    name = request.args.get('name', '')

    # Forward the request to Spade
    response = requests.get("https://east.sandbox.spade.com/merchants", params={"name": name}, headers={"X-Api-Key": spade_api_key})

    # Relay Spade's response to your frontend
    return response.json(), response.status_code

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 the simple-svelte-autocomplete package:

<script>
import AutoComplete from "simple-svelte-autocomplete";

async function getMerchants(name) {
  const url = "https://<YOUR_API_DOMAIN_HERE>/merchants?name=" + encodeURIComponent(name);

  const response = await fetch(url);
  const json = await response.json();

  return json.results;
}
</script>

<AutoComplete
  searchFunction="{getMerchants}"
  delay="400"
  localFiltering={false}
  labelFieldName="name"
  valueFieldName="id"
  bind:selectedItem="{selectedMerchant}"
/>;

⚠
In this example, we're using the simple-svelte-autocomplete package's built-in throttling functionality (this is what the delay="400" setting configures).
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.

Conclusion

You've just learned how Spade's merchant search endpoint can be used to get detailed merchant information. Now you're ready start making some queries and make fine-grained transaction processing decisions on top of Spade's rich data.

Additional Resources

Spending Controls Guide

Overview

Searching for a merchant

Understanding merchant search results

Third Party Information

Counterparty Information

Integrating merchant search into your application

Step 1: Set up a proxy endpoint on your backend

Step 2: Add the autocomplete input to your frontend

In this example, we're using the simple-svelte-autocomplete package's built-in throttling functionality (this is what the delay="400" setting configures).

Conclusion

Additional Resources

In this example, we're using the `simple-svelte-autocomplete` package's built-in throttling functionality (this is what the `delay="400"` setting configures).