API ReferenceChangelog
API Reference

Batch Merchant Matching Guide

ⓘ Reading Time: 10 mins

Batch merchant matching allows you to efficiently match a large volume of merchants to Locations and Counterparties in Spade's Database. You can submit up to 50,000 merchants in a single request and retrieve the matching results once processing is complete. In this guide, we'll use the /batches/merchants/match POST endpoint to submit a batch of merchants, the /batches/{batchId} GET endpoint to check the batch status, and the /batches/{batchId}/results GET endpoint to retrieve the results.

⚠

Merchant matching is not enabled by default. To request access, please contact us at sales@spade.com.

Getting Started

  1. Submit Your Batch of Merchants:
import requests

# Prepare your batch of merchants
merchants = [
    {
        "id": "unique_id_123",
        "merchantName": "Amazon",
        "location": {
            "address": "1234 W 5th Ave",
            "city": "New York",
            "region": "NY",
            "country": "USA",
            "postalCode": "10001"
        }
    },
    # ... more merchants ...
]

# Submit the batch
response = requests.post(
    "https://east.sandbox.spade.com/batches/merchants/match",
    json={"merchants": merchants},
    headers={"X-Api-Key": "<Your API Key Here>"}
)

batch_id = response.json()["batch_id"]
print(f"Batch submitted with ID: {batch_id}")
  1. Check the Batch Status Until It's Complete:

Refer to the Batch Enrichment Guide for details on how to check the batch status and handle responses.

  1. Retrieve the Results:

Once the batch is complete, retrieve the results:

# Get the matched results
response = requests.get(
    f"https://east.sandbox.spade.com/batches/{batch_id}/results",
    headers={"X-Api-Key": "<Your API Key Here>"}
)

results = response.json()["matches"]

# Process your matched merchants
for match in results:
    print(f"Matched Merchant ID: {match['merchantId']}")
    print(f"Counterparty Name: {match['counterpartyName']}")
    print(f"Spade's Counterparty ID: {match['counterpartyId']}")

Handling Non-Matches

It's possible that there is either no counterparty and/or location match for a merchant given the provided input.
In these cases, you can still expect a response object in the matches array. However, the counterpartyId and/or location.id will be null for the corresponding merchant.

Best Practices

For best practices regarding unique IDs, status polling, timeouts, and error handling, please refer to the Batch Enrichment Guide.