> ## 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 guide

> Batch merchant enrichment is not enabled by default. To request access, please contact us.

***

<Info>
  Batch merchant enrichment is not enabled by default. To request access, please
  contact us at [sales@spade.com](mailto:sales@spade.com)
</Info>

## 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](/reference/microbatch-enrichment-guide).

***

## Request Schema

The request body wraps your merchants in a `merchants` array.

<CodeGroup>
  ```json Required Fields theme={null}
  {
    "merchants": [
      {
        "id": "123",
        "merchantName": "Costco Wholesale",
        "website": "https://www.costco.com"
      }
    ]
  }
  ```

  ```json All Fields theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

> **`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

<CodeGroup>
  ```python Python theme={null}
  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())

  ```

  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```
</CodeGroup>

***

## Asynchronous Response (default)

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

<CodeGroup>
  ```json Response theme={null}
  {
    "batchId": "8590f0f5-2a4b-431e-baa8-cd3bfff22020",
    "status": "pending",
    "batchSize": 5000,
    "submittedAt": "2026-04-09T10:23:45.123Z"
  }
  ```
</CodeGroup>

<Note>Store the `batchId` — you'll need it to retrieve results.</Note>

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](/reference/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.

<CodeGroup>
  ```python Python theme={null}
  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']}")

  ```

  ```bash cURL theme={null}
  curl https://east.sandbox.spade.com/batches/<BATCH_ID>/results \
    -H "X-Api-Key: <YOUR_SANDBOX_API_KEY>"
  ```
</CodeGroup>

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

***

## 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.

```json theme={null}
{
  "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.