List Merchants

Returns a paginated list of merchants under a specific partner. This endpoint is only available for partners at the Master Merchant level.

Endpoint

GET /Partners/{id}/merchants

Authentication

X-Api-Key: {adminApiKey}

Path parameters

Name	Type	Required	Description
id	string	Yes	The partnerId of the Master Merchant partner whose merchants you want to list

Query parameters

Parameter	Type	Required	Description
Status	string	No	Filter by merchant status. See Merchant Management for valid values
Search	string	No	Search by company name
SortBy	string	No	Field to sort by. Supported values: Created, Updated, CompanyName
SortDirection	string	No	asc or desc
Page	integer	No	Page number, zero-indexed. Defaults to 0
PageSize	integer	No	Number of results per page. Defaults to 50, max 100

Request headers

Header	Value
X-Api-Key	{adminApiKey}
Accept	application/json

Example request

curl -X GET "https://api.test.devs.beadpay.io/Partners/{partnerId}/merchants?Page=0&PageSize=50" \
     -H "X-Api-Key: {adminApiKey}"

Successful response — 200

The response is a paginated wrapper containing an array of merchant objects.

{
  "data": [
    {
      "merchant": {
        "id": "mer_123123",
        "partnerId": "part_e9ab6c82b6d74a4f9c33",
        "companyName": "Acme Coffee Roasters",
        "status": "active",
        "tenderTypes": ["ethereum", "usdcBase"],
        "receivableCurrencyIds": [1],
        "isSettlementOnly": false,
        "isCommissionMerchant": false,
        "created": "2025-06-04T18:41:14.402Z",
        "updated": "2025-06-04T18:41:14.402Z"
      },
      "details": null
    }
  ],
  "total": 1,
  "page": 0
}

Response fields

Field	Description
data	Array of merchant objects
data[].merchant	Core merchant record — see Get Merchant for full field reference
data[].details	Extended KYB details object, or null if not available
total	Total number of merchants matching the query
page	Current page number, zero-indexed

Error responses

Code	Condition
401	Missing or invalid API key
403	Authenticated but not permitted to list merchants for this partner, or partner is not a Master Merchant
404	Partner {id} does not exist or is not visible to your key

Best practices

• Confirm the partner is at the Master Merchant level before calling this endpoint — other partner types will return a 403

• Use Status=active to filter to merchants ready for production traffic

• Use Search to locate a specific merchant by company name rather than fetching all pages

• Store total to drive pagination logic in your UI

Related pages

• Get Merchant

• Merchant Management

• Partner Management