curl "https://api.khaime.com/api/v1/merchants?page=1&limit=20" \
-H "X-API-Key: pk_sandbox_your_key"
Marketplace
List Merchants
List all sub-merchants in your marketplace.
GET
/
merchants
curl "https://api.khaime.com/api/v1/merchants?page=1&limit=20" \
-H "X-API-Key: pk_sandbox_your_key"
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 amerchant_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
{
"success": true,
"message": "Merchants retrieved successfully",
"data": {
"merchants": [
{
"id": 3,
"marketplace_id": 1042,
"merchant_id": 1676,
"commission_rate": "0.0800",
"status": "active",
"invite_token": null,
"invited_at": null,
"joined_at": "2026-03-28T11:33:21.646Z",
"created_at": "2026-03-28T11:33:21.646Z",
"updated_at": "2026-03-28T11:33:21.646Z",
"merchant": {
"id": 1676,
"business_email": "merchant@example.com"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"pages": 1
}
}
}
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 holds the merchant’s email address — note it doesn’t match the business_email name used elsewhere in the response.Response Fields
| Field | Type | Description |
|---|---|---|
merchants[].id | integer | Marketplace-merchant relationship ID |
merchants[].marketplace_id | integer | Operator’s business ID |
merchants[].merchant_id | integer | Sub-merchant’s business ID |
merchants[].commission_rate | string | Decimal commission rate (e.g., "0.0800" = 8%) |
merchants[].status | string | active or suspended |
merchants[].joined_at | string | ISO 8601 timestamp when the merchant was linked |
merchants[].merchant | object | Nested merchant details |
merchants[].merchant.id | integer | Merchant’s business ID |
merchants[].merchant.business_email | string | Merchant’s email address |
pagination | object | Pagination metadata |
joined_at descending — most recently joined first.
Error Codes
| Status | Error Code | Cause |
|---|---|---|
401 | — | Missing or invalid X-API-Key header. |
403 | AUTH_PERMISSION_DENIED | Your business isn’t set up as a marketplace operator. |
curl "https://api.khaime.com/api/v1/merchants?page=1&limit=20" \
-H "X-API-Key: pk_sandbox_your_key"
Whys
Filtering bystatus 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 bystatus — 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.