Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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.

POST https://api.rapidchargeback.com/api/v1/merchants/batch
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json

FieldTypeRequiredDescription
itemsarrayYesFrom 1 to 500 merchants, each with the fields of Create or update merchant
on_name_conflictenumNoerror (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.

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.

Terminal window
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" }
]
}'

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" }
}
}
]
}
}
FieldDescription
totalItems sent
succeededItems created, updated or unchanged (total - failed)
failedRejected items
countsHow many of each: created, updated, unchanged
resultsOne per item, in the order of the array sent
results[].indexPosition of the item in the array sent, starting at 0
results[].resultcreated, updated, unchanged or error
results[].merchant_refThe merchant_ref you sent in the item (null if it was not text)
results[].merchantOn success: the merchant summary, the same as in List merchants
results[].warningsWhen present: the SERVICE_FIELDS_NOT_APPLIED notice (see Notice of data that does not apply right away)
results[].statusOn error: the HTTP status the item would get on its own
results[].errorOn 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.

HTTP/1.1 429 Too Many Requests
Retry-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.

HTTPCodeWhen
422VALIDATION_ERRORInvalid envelope: items missing, empty, with more than 500, or an unknown field in the envelope
413PAYLOAD_TOO_LARGEBody above 5 MB
429RATE_LIMIT_EXCEEDEDMore than 60 writes per minute (each batch counts as one)
429BATCH_IN_PROGRESSAnother merchant batch from your company is still in progress
403KYB_NOT_APPROVED, COMPANY_NOT_ACTIVE, COMPANY_BLOCKEDSee Create or update merchant
503SERVICE_UNAVAILABLETemporarily unavailable: repeat after Retry-After

  • 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 and Response codes.