> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Merchants

> List all sub-merchants in your marketplace.

# List Merchants

Retrieve all sub-merchants registered under your marketplace, with pagination.

## Query Parameters

<ParamField query="status" type="string" default="active">
  Filter by merchant status. Default: `active`.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Default: `1`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Number of results per page. Maximum: `100`. Default: `20`.
</ParamField>

## Response

```json theme={null}
{
  "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,
          "educator_email": "merchant@example.com"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "pages": 1
    }
  }
}
```

### 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.educator_email` | string  | Merchant's email address                        |
| `pagination`                          | object  | Pagination metadata                             |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.khaime.com/api/v1/partner/marketplace/merchants?page=1&limit=20" \
    -H "X-API-Key: pk_sandbox_your_key"
  ```
</RequestExample>