---
updatedAt: 2026-04-21T09:29:18.000Z
agentTools:
  projectIndex: https://partner.getpliant.com/llms.txt
---

# List Merchants

> 🔒 **Required scope:** `spend:read`
>
> The API credential calling this endpoint must be granted the `spend` category with `read` or `read & write` access.
> Scopes are assigned to the credential when it is created or edited in Pliant, not requested when obtaining the access token.
> A credential without this scope receives `403 Forbidden` with the error code `INSUFFICIENT_PERMISSION`.

Returns a list of all merchants for the given organization. This only returns merchants that have been used by this organization so far. You can use the `limit`, `page`, `sortBy` and `sortDirection` parameters to filter and sort the results.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "contact": {
      "name": "API Support",
      "email": "support@getpliant.com",
      "url": "https://www.getpliant.com"
    },
    "title": "Pliant Partner API",
    "description": "Pliant Partner API",
    "version": "2.1.0",
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/license/MIT"
    }
  },
  "servers": [
    {
      "url": "https://partner-api.getpliant.com/api",
      "description": "Pliant Production Server"
    },
    {
      "url": "https://sandbox.partner-api.getpliant.com/api",
      "description": "Pliant Sandbox Server"
    },
    {
      "url": "https://pci-api.getpliant.com",
      "description": "PCI Vault Production Server"
    },
    {
      "url": "https://pci-sandbox.partner-api.getpliant.com",
      "description": "PCI Vault Sandbox Server"
    }
  ],
  "x-readme": {
    "explorer-enabled": false,
    "samples-languages": [
      "curl",
      "java",
      "kotlin"
    ],
    "headers": [
      {
        "key": "Pliant-API-Version",
        "value": "2.1.0"
      }
    ]
  },
  "tags": [
    {
      "name": "Merchants",
      "description": "This tag is for operations related to merchants"
    }
  ],
  "paths": {
    "/merchants": {
      "get": {
        "summary": "List Merchants",
        "description": "> 🔒 **Required scope:** `spend:read`\n>\n> The API credential calling this endpoint must be granted the `spend` category with `read` or `read & write` access.\n> Scopes are assigned to the credential when it is created or edited in Pliant, not requested when obtaining the access token.\n> A credential without this scope receives `403 Forbidden` with the error code `INSUFFICIENT_PERMISSION`.\n\nReturns a list of all merchants for the given organization. This only returns merchants that have been used by this organization so far. You can use the `limit`, `page`, `sortBy` and `sortDirection` parameters to filter and sort the results.\n",
        "x-required-scopes": [
          "spend:read"
        ],
        "tags": [
          "Merchants"
        ],
        "operationId": "get-merchants",
        "parameters": [
          {
            "name": "organizationId",
            "required": true,
            "in": "query",
            "description": "The unique identifier of the organization.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "The maximum number of items to return per page. The default value if not provided is 100, the maximum allowed value is 1000.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "The page number to return, starting with 0, this counts up to the total number of pages. The total number of pages is determined by the total number of records divided by the limit.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "sortBy",
            "in": "query",
            "description": "The field to sort by.",
            "schema": {
              "type": "string",
              "enum": [
                "organizationId",
                "name",
                "createdAt"
              ]
            }
          },
          {
            "name": "sortDirection",
            "in": "query",
            "description": "The direction to sort by.",
            "schema": {
              "type": "string",
              "enum": [
                "ASC",
                "DESC"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ok",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Merchant"
                      }
                    },
                    "hasNextPage": {
                      "type": "boolean",
                      "description": "Indicates whether there is a next page available."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400"
          },
          "401": {
            "$ref": "#/components/responses/401"
          },
          "403": {
            "$ref": "#/components/responses/403"
          },
          "429": {
            "$ref": "#/components/responses/429"
          },
          "500": {
            "$ref": "#/components/responses/500"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "This API uses oAuth2 with client credentials flow to [obtain the Bearer Token](/docs/authenticated-api-usage).",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "Merchant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Unique identifier of the merchant internal to Pliant."
          },
          "displayName": {
            "type": "string",
            "description": "The display name of the merchant."
          },
          "logoPath": {
            "type": "string",
            "description": "The path to the logo of the merchant."
          },
          "mcc": {
            "type": "string",
            "nullable": true,
            "description": "The MCC (Merchant Category Code) for the merchant."
          },
          "mccDescription": {
            "type": "string",
            "nullable": true,
            "description": "A description for the merchant's MCC code."
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "errorCode": {
            "type": "string",
            "description": "The error code"
          },
          "exceptionId": {
            "type": "string",
            "format": "uuid",
            "description": "The id of the exception that was thrown"
          },
          "message": {
            "type": "string",
            "description": "The cause of the error or further explanations on the error"
          }
        }
      }
    },
    "responses": {
      "400": {
        "description": "Bad Request. The API consumer sent a malformed request which could not be processed.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "401": {
        "description": "Unauthorized. The API consumer is not authorized to access the requested resource.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "403": {
        "description": "Forbidden. The API consumer is not allowed to access the requested resource.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "429": {
        "description": "Too Many Requests. The API consumer has sent too many requests in a given amount of time. Please check our [API guidelines](/docs/pliant-api-guidelines#api-rate-limits).",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string",
                  "description": "Detailed description of the error and breached rate limit."
                }
              }
            }
          }
        }
      },
      "500": {
        "description": "Internal Server Error. The request was not completed due to an internal error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}
```