Batch merchant enrichment guide

Batch merchant enrichment is not enabled by default. To request access, please contact us at sales@spade.com

Overview

Batch merchant enrichment allows you to enrich a large volume of merchants with industry classification, predicted Merchant Category Code (MCC), and payment acceptance details in a single request. You can submit up to 50,000 merchants per batch. Given a merchant name and either a website or location details, Spade returns:

Predicted MCC: A list of the most likely Merchant Category Codes for the merchant.
Industry classification: A hierarchical industry taxonomy, from broadest category to most specific.
Payment acceptance signals: Whether the merchant accepts cards, processes transactions online or in-person, and payment platforms/technologies used by the merchant.

By default, all batches are processed asynchronously — you’ll receive a batchId to check status and retrieve results once processing is complete. This endpoint also supports microbatching for small batches (up to 50 merchants); see the Microbatch enrichment guide.

Request Schema

The request body wraps your merchants in a merchants array.

{
  "merchants": [
    {
      "id": "123",
      "merchantName": "Costco Wholesale",
      "website": "https://www.costco.com"
    }
  ]
}

{
  "merchants": [
    {
      // REQUIRED
      "id": "123",
      "merchantName": "Costco Wholesale",

      // Make sure to include either website or location details--include both for best performance.
      "website": "https://www.costco.com",
      "address": "976 3rd Ave",
      "city": "Brooklyn",
      "region": "NY",
      "country": "USA",
      "postalCode": "11232",
      "latitude": 40.6602,
      "longitude": -74.0038,

      // OPTIONAL – controls corporation vs. location matching
      "level": "location"
    }
  ],

  // OPTIONAL
  "callbackUrl": "https://example.com/batch-notifications"
}

level field: Use "corporation" when you want brand-level information (e.g. Costco in general) or "location" when you want information about a specific physical location (e.g. one specific Costco location). Defaults to "location" if not specified.

Sending the Request

import requests
import pprint

merchants = [
{
"id": "123",
"merchantName": "Costco Wholesale",
"website": "https://www.costco.com",
"address": "976 3rd Ave",
"city": "Brooklyn",
"region": "NY",
"country": "USA",
"postalCode": "11232"
},

# ... more merchants ...

]

response = requests.post(
"https://east.sandbox.spade.com/batches/merchants/enrich",
headers={"X-Api-Key": "<YOUR_SANDBOX_API_KEY>"},
json={"merchants": merchants},
timeout=30,
)
pprint.pp(response.json())

curl https://east.sandbox.spade.com/batches/merchants/enrich \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <YOUR_SANDBOX_API_KEY>" \
  -d '{
    "merchants": [
      {
        "id": "123",
        "merchantName": "Costco Wholesale",
        "website": "https://www.costco.com",
        "address": "976 3rd Ave",
        "city": "Brooklyn",
        "region": "NY",
        "country": "USA",
        "postalCode": "11232"
      }
    ]
  }'

Asynchronous Response (default)

By default, the response returns a batchId you can use to check status and retrieve results.

{
  "batchId": "8590f0f5-2a4b-431e-baa8-cd3bfff22020",
  "status": "pending",
  "batchSize": 5000,
  "submittedAt": "2026-04-09T10:23:45.123Z"
}

Store the batchId — you’ll need it to retrieve results.

To receive a notification when processing completes, include a callbackUrl in your submission. For full details on callbacks and polling, refer to the Batch Enrichment Guide. Both batch endpoints use the same callback mechanism.

Retrieving Results

Once the batch status is completed, retrieve results via the /batches/{batchId}/results endpoint.

response = requests.get(
    f"https://east.sandbox.spade.com/batches/{batch_id}/results",
    headers={"X-Api-Key": "<YOUR_SANDBOX_API_KEY>"}
)

data = response.json()
for result in data["results"]:
print(f"ID: {result['id']}")
print(f"Predicted MCC: {result['predictedMcc']}")
print(f"Industry: {result['industry']}")

curl https://east.sandbox.spade.com/batches/<BATCH_ID>/results \
  -H "X-Api-Key: <YOUR_SANDBOX_API_KEY>"

The /batches/{batchId}/results endpoint returns a 202 status code if the batch is not yet complete. Poll until you receive a 200.

Response Breakdown

predictedMcc

The predictedMcc field contains a list of relevant merchant category codes for the merchant.

Field	Description
`code`	The predicted MCC code (4-digit string).
`description`	Human-readable description of the MCC code.

industry

The industry field contains a list of categories ordered from broadest to most specific.

Field	Description
`id`	Category identifier (e.g., “011-000-000-000”).
`name`	Human-readable category name (e.g., “Gas Stations”).
`icon`	URL to the category icon.

Payment acceptance fields

Field	Description
`isActivelyProcessingCardTransactions`	Whether the merchant is actively processing card transactions.
`isCardAccepting`	Whether the merchant accepts card payments.
`acceptsOnlinePayment`	Whether the merchant accepts online/e-commerce payments.
`acceptsBrickAndMortarPayment`	Whether the merchant accepts in-person payments.
`knownTechnologies`	An array of payment technologies used by the merchant.

Error Handling

Invalid merchants are not rejected outright — they appear in the results array with a statusCode of 400 and an errors object describing what went wrong. Valid merchants in the same batch are still processed normally.

{
  "id": "456",
  "statusCode": 400,
  "errors": {
    "merchantName": ["This field is required."]
  }
}

Implementation Notes

Content-Type must be application/json.
400 errors on the batch submission itself indicate a malformed request (e.g., no merchants provided, duplicate id values, or exceeding the 50,000 merchant limit).
403 errors — Invalid or missing API key.
500 errors — Spade infrastructure issue. Exponential back-off is recommended before resubmitting.

Welcome

Enrichment Guides

Tooling Guides

More

Batch merchant enrichment guide

Overview

Request Schema

Sending the Request

Asynchronous Response (default)

Retrieving Results

Response Breakdown

predictedMcc

industry

Payment acceptance fields

Error Handling

Implementation Notes

​Overview

​Request Schema

​Sending the Request

​Asynchronous Response (default)

​Retrieving Results

​Response Breakdown

​predictedMcc

​industry

​Payment acceptance fields

​Error Handling

​Implementation Notes

Overview

Request Schema

Sending the Request

Asynchronous Response (default)

Retrieving Results

Response Breakdown

predictedMcc

industry

Payment acceptance fields

Error Handling

Implementation Notes