Skip to content

↑↓ navigate ↵ open Ctrl↵ new tab esc close

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.

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_DUPLICATE with the merchant_id of the merchant that already has the name. Save the reference on it once with Edit 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

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 with retry_rejected: true.

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):

  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.

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.

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.

Usage by merchant returns how many billable alerts each seller had in the current billing cycle or in a closed one.

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.


LimitValue
Items per batch500
Writes per minute (each batch counts as one)60 per company
Batches at the same time1 merchant batch and 1 enrollment batch per company (BATCH_IN_PROGRESS)
Enrollments waiting for approval20,000 per company (ENROLLMENT_PENDING_LIMIT)
Usage queries per minute10 per company

See also Rate limit.