Skip to main content

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.

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"
    }
  ]
}
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())

​
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']}")
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.
FieldDescription
codeThe predicted MCC code (4-digit string).
descriptionHuman-readable description of the MCC code.

​
industry

The industry field contains a list of categories ordered from broadest to most specific.
FieldDescription
idCategory identifier (e.g., “011-000-000-000”).
nameHuman-readable category name (e.g., “Gas Stations”).
iconURL to the category icon.

​
Payment acceptance fields

FieldDescription
isActivelyProcessingCardTransactionsWhether the merchant is actively processing card transactions.
isCardAcceptingWhether the merchant accepts card payments.
acceptsOnlinePaymentWhether the merchant accepts online/e-commerce payments.
acceptsBrickAndMortarPaymentWhether the merchant accepts in-person payments.
knownTechnologiesAn 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.