# Edit merchant

> Changes a merchant's registration by merchant_id and saves the merchant_ref on a merchant that has none yet. The reference cannot be changed once saved.

Página: https://doc.rapidchargeback.com/en/canais/merchants/editar-merchant/

Changes the registration of one of your company's merchants by `merchant_id`. It is also how you save the `merchant_ref` on a merchant that already existed without a reference (for example, one registered in the dashboard): after that, [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/) and the [Merchant batch](https://doc.rapidchargeback.com/en/canais/merchants/lote-de-merchants/) update it by the reference.

## Endpoint

```
PATCH https://api.rapidchargeback.com/api/v1/merchants/:merchant_id
```

## Authentication

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

---

## URL parameters

| Param | Type | Description |
|---|---|---|
| `merchant_id` | string (UUID) | The merchant `id` |

## Request body

Any field of [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/#request-body), all optional, with the same limits. `on_name_conflict` does not exist here.

- Send only what changes. A field that was not sent stays as it is; `null` or `""` clears it (except `name`).
- Empty body (`{}`): `422 VALIDATION_ERROR` "Send at least one field".
- Name of another merchant of yours: `409 MERCHANT_DUPLICATE`, with its `merchant_id`.

### `merchant_ref`: saved once

| Situation | Response |
|---|---|
| The merchant has no reference | Saves the one sent |
| The one sent equals the saved one | Nothing changes (`unchanged`, if no other field changed) |
| The merchant already has another reference | `409 MERCHANT_REF_IMMUTABLE`: the reference cannot be changed |
| Another merchant of yours already uses that reference | `409 MERCHANT_REF_TAKEN`, with its `merchant_id` |

The reference cannot be changed because transactions and webhook deliveries already made with it keep pointing to the same merchant. If two merchants need to become one, contact Rapid support.

### `status`

`active` or `inactive`. It is informational: `inactive` does not stop alerts or transactions. To stop receiving alerts for a merchant, [request the deactivation](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-desativacao/) of its enrollments.

---

## Request example

Save the reference from your system on a merchant that came from the dashboard:

```bash
curl -X PATCH https://api.rapidchargeback.com/api/v1/merchants/00000000-0000-0000-0000-000000000001 \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_ref": "PB-1001" }'
```

---

## Response

### Success

```
HTTP/1.1 200 OK
```

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Loja Exemplo",
    "merchant_ref": "PB-1001",
    "status": "active",
    "created_at": "2026-03-10T12:00:00.000Z",
    "updated_at": "2026-11-06T12:00:00.000Z",
    "...": "full registration"
  },
  "meta": { "result": "updated", "warnings": [] }
}
```

`data` is the full registration, the same as in [Get merchant](https://doc.rapidchargeback.com/en/canais/merchants/consultar-merchant/). `meta.result` is `updated` or `unchanged` (nothing changed, nothing saved); `meta.warnings` may bring 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)).

### Reference already saved

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "MERCHANT_REF_IMMUTABLE",
    "message": "merchant_ref cannot be changed once set"
  }
}
```

### Errors

| HTTP | Code | When |
|---|---|---|
| 404 | `MERCHANT_NOT_FOUND` | The merchant does not exist, belongs to another company, or the id is not a UUID |
| 409 | `MERCHANT_DUPLICATE` | Another merchant of yours already has the name |
| 409 | `MERCHANT_REF_IMMUTABLE` | The merchant already has another reference |
| 409 | `MERCHANT_REF_TAKEN` | Another merchant of yours already uses the reference (`params.merchant_id`) |
| 422 | `VALIDATION_ERROR`, `FIELD_REQUIRED`, `FIELD_TOO_LONG`, `FIELD_INVALID`, `FIELD_INVALID_OPTION` | See [Create or update merchant](https://doc.rapidchargeback.com/en/canais/merchants/criar-ou-atualizar-merchant/#errors) |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Company without an approved registration, inactive or blocked |
| 429 | `RATE_LIMIT_EXCEEDED` | More than 60 writes per minute |
| 503 | `SERVICE_UNAVAILABLE` | Temporarily unavailable: repeat after `Retry-After` |

---

## Notes

- **Repeating is safe:** the same edit again comes back `unchanged`.
- **Activity:** every change shows up in the dashboard Activity as made by the integration.
