# Sync guide

> The recommended flow to keep your sellers, their enrollments and the alerts up to date with Rapid through the API, without duplicating anything.

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

This guide is for anyone with many sellers (stores, brands, sub-accounts) who wants to keep their registration at Rapid the same as in their own system, request the enrollments and link each alert to the right seller. Everything relies on `merchant_ref`, the seller ID in **your** system.

## 1. Merchants: the whole base, every day

Send your seller base through the [Merchant batch](https://doc.rapidchargeback.com/en/canais/merchants/lote-de-merchants/), up to 500 per call, once a day (or whenever it changes). The key is the `merchant_ref`:

- a new seller becomes a new merchant (`created`);
- a seller that changed is updated (`updated`);
- an identical seller is not saved (`unchanged`), so resending the whole base creates no false change.

Watch out for:

- **A merchant already in the dashboard, with no reference.** The batch responds `MERCHANT_DUPLICATE` with the `merchant_id` of the merchant that already has the name. Save the reference on it once with [Edit merchant](https://doc.rapidchargeback.com/en/canais/merchants/editar-merchant/) (`PATCH` with `merchant_ref`); from then on the batch updates it.
- **`merchant_ref` ignores case and accents.** `PB-a1` and `pb-A1` are the same reference. If your system has sellers that differ only in that, the API rejects the second one with `MERCHANT_REF_CONFLICT` instead of merging the two.
- **The reference cannot be changed** once saved (`MERCHANT_REF_IMMUTABLE`).

## 2. Enrollments: requested once, when the seller joins

The enrollment is what links alerts to a merchant: its descriptor or its BIN + CAID (see [Enrollments](https://doc.rapidchargeback.com/en/canais/enrollments/visao-geral/)). Request each one **once**, when the seller joins your base, with [Request enrollment](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-enrollment/) or the [Enrollment batch](https://doc.rapidchargeback.com/en/canais/enrollments/lote-de-enrollments/). Do not include enrollments in the daily upload.

- Requesting the same enrollment again returns `existing`, without creating another one: repeating after a failure is safe.
- Every request goes through approval by the Rapid team and starts as `pending`.
- A request rejected by the team does not come back on its own: requesting it again responds `ENROLLMENT_PREVIOUSLY_REJECTED`. Fix the data and send it with `retry_rejected: true`.

## 3. Following the approval

Query [List enrollments](https://doc.rapidchargeback.com/en/canais/enrollments/listar-enrollments/) with `updated_since` every few minutes. The rule is the same in the three lists that accept this filter (merchants, enrollments and alerts):

1. Keep the highest `updated_at` you received.
2. On the next query, send that value **minus 2 minutes** as `updated_since`.
3. Skip the (`id`, `updated_at`) pair you already processed.
4. Read the pages up to `total_pages`.

The status of each product in the enrollment tells where it stands: `pending`, `active`, `rejected` (with `rejection_reason`), `deactivation_requested` or `inactive`.

## 4. Alerts with your seller

Each alert brings the seller's `merchant_ref`, in the [alerts query](https://doc.rapidchargeback.com/en/callback/consultar-alertas/) and in the [webhook](https://doc.rapidchargeback.com/en/canais/webhook/payload/) in `v2` format (in `merchant.merchant_ref`), along with the `merchant_enrollment_id` of the enrollment that matched. To fetch a seller's alerts, filter by `merchant_ref`. To fetch what changed, use `updated_since` with the same rule as step 3.

## 5. A seller leaving

List its enrollments with [List enrollments](https://doc.rapidchargeback.com/en/canais/enrollments/listar-enrollments/) filtering by `merchant_ref` and [request the deactivation](https://doc.rapidchargeback.com/en/canais/enrollments/pedir-desativacao/) of each one. The Rapid team confirms it, and the enrollment keeps receiving alerts until the confirmation. If you want, mark the merchant with `status: "inactive"` in [Edit merchant](https://doc.rapidchargeback.com/en/canais/merchants/editar-merchant/).

## 6. Monthly usage per seller

[Usage by merchant](https://doc.rapidchargeback.com/en/canais/uso/uso-por-merchant/) returns how many billable alerts each seller had in the current billing cycle or in a closed one.

## 7. Before the real load

There is no test environment yet: every enrollment request made in your account really goes into the Rapid team's approval queue. Before the first large load, contact Rapid support to agree on how to validate your integration.

---

## Limits that apply to this flow

| Limit | Value |
|---|---|
| Items per batch | 500 |
| Writes per minute (each batch counts as one) | 60 per company |
| Batches at the same time | 1 merchant batch and 1 enrollment batch per company (`BATCH_IN_PROGRESS`) |
| Enrollments waiting for approval | 20,000 per company (`ENROLLMENT_PENDING_LIMIT`) |
| Usage queries per minute | 10 per company |

See also [Rate limit](https://doc.rapidchargeback.com/en/referencia/codigos-de-resposta/#rate-limit).
