Sync guide
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
Section titled “1. Merchants: the whole base, every day”Send your seller base through the Merchant batch, 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_DUPLICATEwith themerchant_idof the merchant that already has the name. Save the reference on it once with Edit merchant (PATCHwithmerchant_ref); from then on the batch updates it. merchant_refignores case and accents.PB-a1andpb-A1are the same reference. If your system has sellers that differ only in that, the API rejects the second one withMERCHANT_REF_CONFLICTinstead of merging the two.- The reference cannot be changed once saved (
MERCHANT_REF_IMMUTABLE).
2. Enrollments: requested once, when the seller joins
Section titled “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). Request each one once, when the seller joins your base, with Request enrollment or the Enrollment batch. 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 withretry_rejected: true.
3. Following the approval
Section titled “3. Following the approval”Query List enrollments with updated_since every few minutes. The rule is the same in the three lists that accept this filter (merchants, enrollments and alerts):
- Keep the highest
updated_atyou received. - On the next query, send that value minus 2 minutes as
updated_since. - Skip the (
id,updated_at) pair you already processed. - 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
Section titled “4. Alerts with your seller”Each alert brings the seller’s merchant_ref, in the alerts query and in the webhook 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
Section titled “5. A seller leaving”List its enrollments with List enrollments filtering by merchant_ref and request the deactivation 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.
6. Monthly usage per seller
Section titled “6. Monthly usage per seller”Usage by merchant returns how many billable alerts each seller had in the current billing cycle or in a closed one.
7. Before the real load
Section titled “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
Section titled “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.