Merchant batch
Creates or updates up to 500 merchants in one call. Each item follows exactly the rule of Create or update 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
Section titled “Endpoint”https://api.rapidchargeback.com/api/v1/merchants/batchAuthentication
Section titled “Authentication”Authorization: Basic base64(client_id:client_secret)Content-Type: application/jsonRequest body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
items | array | Yes | From 1 to 500 merchants, each with the fields of Create or update merchant |
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
itemsandon_name_conflictin the envelope, oritemsempty or with more than 500: the whole batch is rejected with422 VALIDATION_ERROR, saving nothing.
Repeated in the same batch
Section titled “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
nameunder different references (withoutappend_ref):MERCHANT_NAME_DUPLICATE_IN_BATCH.
Request example
Section titled “Request example”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
Section titled “Response”Success
Section titled “Success”200 OK whenever the batch was processed, even with rejected items. Check failed and each item’s result.
{ "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 |
results[].warnings | When present: the SERVICE_FIELDS_NOT_APPLIED notice (see 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, plus the two for repeats in the batch.
Another batch in progress
Section titled “Another batch in progress”HTTP/1.1 429 Too Many RequestsRetry-After: 5{ "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
Section titled “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 |
| 503 | SERVICE_UNAVAILABLE | Temporarily unavailable: repeat after Retry-After |
- Repeating is safe. After a
503or a dropped connection, send the same batch: what was already saved comes backunchanged. - 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 and Response codes.