# Merchant batch

> Creates or updates up to 500 merchants in one call, by merchant_ref, with the result of each item in the order sent.

Página: https://doc.rapidchargeback.com/en/canais/merchants/lote-de-merchants/

Creates or updates up to **500 merchants** in one call. Each item follows exactly the rule of [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/): the key is the `merchant_ref`, what did not change is not saved, and repeating the batch duplicates nothing.

The batch is always **partial**: each item is saved or rejected on its own, and the response says what happened to each one, in the same order as sent.

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/merchants/batch
```

## Authentication

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `items` | array | Yes | From 1 to 500 merchants, each with the fields of [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/#request-body) |
| `on_name_conflict` | enum | No | `error` (default) or `append_ref`, for all items. An item's own `on_name_conflict` takes precedence |

- Body up to **5 MB**. Above that, `413 PAYLOAD_TOO_LARGE`.
- A field other than `items` and `on_name_conflict` in the envelope, or `items` empty or with more than 500: the whole batch is rejected with `422 VALIDATION_ERROR`, saving nothing.

### Repeated in the same batch

The first item counts; the following ones are rejected, without saving:

- same `merchant_ref` (ignoring case and accents): `MERCHANT_REF_DUPLICATE_IN_BATCH`;
- same `name` under different references (without `append_ref`): `MERCHANT_NAME_DUPLICATE_IN_BATCH`.

---

## Request example

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/merchants/batch \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "merchant_ref": "PB-1001", "name": "Loja Exemplo" },
      { "merchant_ref": "PB-1002", "name": "Loja Exemplo Dois", "merchant_url": "https://lojaexemplodois.com" },
      { "merchant_ref": "PB-1003", "name": "Loja Exemplo" }
    ]
  }'
```

---

## Response

### Success

`200 OK` whenever the batch was processed, even with rejected items. Check `failed` and each item's `result`.

```json
{
  "data": {
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "counts": { "created": 1, "updated": 0, "unchanged": 1 },
    "results": [
      {
        "index": 0,
        "result": "unchanged",
        "merchant_ref": "PB-1001",
        "merchant": {
          "id": "00000000-0000-0000-0000-000000000001",
          "name": "Loja Exemplo",
          "merchant_ref": "PB-1001",
          "status": "active",
          "created_at": "2026-11-06T12:00:00.000Z",
          "updated_at": "2026-11-06T12:00:00.000Z"
        }
      },
      {
        "index": 1,
        "result": "created",
        "merchant_ref": "PB-1002",
        "merchant": {
          "id": "00000000-0000-0000-0000-000000000002",
          "name": "Loja Exemplo Dois",
          "merchant_ref": "PB-1002",
          "status": "active",
          "created_at": "2026-11-07T12:00:00.000Z",
          "updated_at": "2026-11-07T12:00:00.000Z"
        }
      },
      {
        "index": 2,
        "result": "error",
        "merchant_ref": "PB-1003",
        "status": 422,
        "error": {
          "code": "MERCHANT_NAME_DUPLICATE_IN_BATCH",
          "message": "name appears more than once in the batch",
          "params": { "name": "Loja Exemplo" }
        }
      }
    ]
  }
}
```

| Field | Description |
|---|---|
| `total` | Items sent |
| `succeeded` | Items created, updated or unchanged (`total - failed`) |
| `failed` | Rejected items |
| `counts` | How many of each: `created`, `updated`, `unchanged` |
| `results` | One per item, in the order of the array sent |
| `results[].index` | Position of the item in the array sent, starting at 0 |
| `results[].result` | `created`, `updated`, `unchanged` or `error` |
| `results[].merchant_ref` | The `merchant_ref` you sent in the item (`null` if it was not text) |
| `results[].merchant` | On success: the merchant summary, the same as in [List merchants](https://doc.rapidchargeback.com/en/canais/merchants/listar-merchants/#success) |
| `results[].warnings` | When present: the `SERVICE_FIELDS_NOT_APPLIED` notice (see [Notice of data that does not apply right away](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/#notice-of-data-that-does-not-apply-right-away)) |
| `results[].status` | On error: the HTTP status the item would get on its own |
| `results[].error` | On error: `code`, `message` and, when present, `params` |

Each item's errors are those of [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/#errors), plus the two for repeats in the batch.

### Another batch in progress

```
HTTP/1.1 429 Too Many Requests
Retry-After: 5
```

```json
{
  "error": {
    "code": "BATCH_IN_PROGRESS",
    "message": "Another batch from this account is still being processed. Try again in a few seconds."
  }
}
```

Your company runs one merchant batch at a time. A second batch sent while the first is still being saved is rejected in full, saving nothing: wait for `Retry-After` and send it again.

### Whole-batch errors

| HTTP | Code | When |
|---|---|---|
| 422 | `VALIDATION_ERROR` | Invalid envelope: `items` missing, empty, with more than 500, or an unknown field in the envelope |
| 413 | `PAYLOAD_TOO_LARGE` | Body above 5 MB |
| 429 | `RATE_LIMIT_EXCEEDED` | More than 60 writes per minute (each batch counts as one) |
| 429 | `BATCH_IN_PROGRESS` | Another merchant batch from your company is still in progress |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | See [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/#errors) |
| 503 | `SERVICE_UNAVAILABLE` | Temporarily unavailable: repeat after `Retry-After` |

---

## Notes

- **Repeating is safe.** After a `503` or a dropped connection, send the same batch: what was already saved comes back `unchanged`.
- **Volume:** 3,000 merchants are 6 calls of 500. Send one batch after the other, not in parallel.
- **Auth, rate limit, error codes:** see [Authentication](https://doc.rapidchargeback.com/en/referencia/autenticacao/) and [Response codes](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/).
