---
updatedAt: 2026-08-14T20:14:47.000Z
agentTools:
  projectIndex: https://docs.staxpayments.com/llms.txt
---

# List Team Merchants

Returns a searchable, paginated list of merchants the caller is authorized to manage. This is the data source for merchant pickers used when granting or editing user access.

For merchant admins, the list is scoped to merchants they hold an active admin membership on. For system_admin users, the list includes all merchants permitted by their godview brand permissions, and a search term (`q`) is required.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "stax-api",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://apiprod.fattlabs.com/"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API key for merchant-level operations. Provides access to merchant-specific endpoints including transactions, payments, customer management, and merchant account settings. This key is scoped to a single merchant account and cannot access partner-level functionality."
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/team/merchants": {
      "get": {
        "summary": "List Team Merchants",
        "description": "Returns a searchable, paginated list of merchants the caller is authorized to manage. This is the data source for merchant pickers used when granting or editing user access.\n\nFor merchant admins, the list is scoped to merchants they hold an active admin membership on. For system_admin users, the list includes all merchants permitted by their godview brand permissions, and a search term (`q`) is required.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Search term to filter merchants by company name or pMID. Required for system_admin callers. For merchant admins, omitting this returns the full administered set.",
            "schema": {
              "type": "string",
              "maxLength": 255
            }
          },
          {
            "name": "per_page",
            "in": "query",
            "required": false,
            "description": "Number of results per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated list of merchants.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The merchant ID."
                          },
                          "company_name": {
                            "type": "string",
                            "description": "The merchant's company name."
                          },
                          "mid": {
                            "type": "string",
                            "nullable": true,
                            "description": "The merchant's pMID."
                          }
                        }
                      }
                    },
                    "current_page": {
                      "type": "integer"
                    },
                    "per_page": {
                      "type": "integer"
                    },
                    "total": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed or the caller does not have team admin access."
          },
          "422": {
            "description": "Validation failed. For system_admin callers, this is returned when the required `q` parameter is missing or `per_page` is out of range."
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```