Skip to main content
GET

Intro

Returns a paginated list of sub-merchants linked to your marketplace, filterable by relationship status.

Context

The entry point for browsing your marketplace roster — grab a merchant_id here, then drill into Get Merchant Details for the full picture, or act on it via Update Merchant, Remove Merchant, or Update Commission. It’s also a quick way to confirm marketplace mode is active on your account — see Setup Marketplace.

Hows

Query Parameters

string
default:"active"
Filter by relationship status. Default: active.
integer
default:"1"
Page number for pagination. Default: 1.
integer
default:"20"
Number of results per page. Maximum: 100. Default: 20.

Response

merchants[].commission_rate is returned as the raw database value — a decimal string like "0.0800", not a JS number. Parse it with Number(...) before doing arithmetic. The nested merchant.educator_email field name is a legacy artifact of the response shape — it is the merchant’s email address.

Response Fields

Results are ordered by joined_at descending — most recently joined first.

Error Codes

Whys

Filtering by status defaulting to active reflects the common case — most integrations want the current working roster, not suspended history. Suspended merchants stay queryable (pass status=suspended) rather than disappearing entirely, since operators sometimes need to audit or reactivate them.

Why nots

This endpoint does not return product counts, payout status, or KYC state for each merchant — it’s intentionally a lightweight roster listing. Call Get Merchant Details per merchant for that. It also doesn’t support filtering by name or email — only by status — so if you need to look up a specific merchant by email, use Get Merchant Details with a known ID, or track the merchant_id returned when you first created or linked them.