# List Merchants

Returns sub-merchants under the authenticated partner account.
Supported query options:
- Pagination: `limit`, `page`
- Text search: `search`
- Sorting: `sort`
- Field filters: `filter[field][eq]=value`

Supported filter fields:
- `id`
- `external_id`
- `name`
- `legal_name`
- `email`
- `underwriting_status`
- `created_at`

Supported sort fields:
- `created_at`
- `id`
- `name`
- `legal_name`

Use `-` prefix for descending sort, for example `sort=-name`.

Endpoint: GET /merchants
Version: partners-v1
Security: bearerAuth, basicAuth

## Query parameters:

  - `limit` (integer)
    Maximum number of merchants to return.

  - `page` (integer)
    Page number for paginated merchant results.

  - `search` (string)
    Case-insensitive text search across merchant `id`, `name`, `email`, and `legal_name`.

  - `sort` (string)
    Sort field for merchant results.

Prefix with `-` for descending order.

  - `filter` (object)
    Filter merchants by allowlisted fields.

Filter semantics: `filter[field][operator]=value`.

Supported filters:
- `filter[id][eq]=mrc_1234567890abcdef`
- `filter[legal_name][eq]=Alpha Supply LLC`
- `filter[underwriting_status][eq]=pending`
- `filter[created_at][eq]=2026-03-11T00:00:00.000Z`

## Response 200 fields (application/json):

  - `count` (integer)
    Example: 2

  - `page` (integer)
    Example: 1

  - `limit` (integer)
    Example: 25

  - `results` (array)

  - `results.id` (string)
    Resolve merchant identifier (lowercase alphanumeric).
For partner API create flows, ID assignment behavior is:
- Resolve may derive a human-friendly alphanumeric candidate from merchant naming fields.
- If the candidate collides with an existing merchant ID, Resolve generates a random lowercase alphanumeric ID.
    Example: mrc_1234567890abcdef

  - `results.legal_business_name` (string)
    Example: Acme Supply LLC

  - `results.dba_name` (string)
    Example: Acme Industrial

  - `results.business_address` (object)

  - `results.business_address.line1` (string, required)
    Example: 100 Main St

  - `results.business_address.line2` (string)
    Example: Suite 200

  - `results.business_address.city` (string, required)
    Example: Austin

  - `results.business_address.state` (string, required)
    Example: TX

  - `results.business_address.postal_code` (string, required)
    Example: 78701

  - `results.business_address.country` (string, required)
    Example: US

  - `results.business_email` (string)
    Example: ops@acmesupply.com

  - `results.business_phone` (string)
    Example: +15125550123

  - `results.entity_type` (string)
    Enum: "corporation", "llc", "sole_proprietorship", "partnership", "non_profit"

  - `results.formation_state` (string)
    Example: TX

  - `results.industry` (string)
    Example: Manufacturing

  - `results.website` (string)
    Example: https://acmesupply.com

  - `results.underwriting_status` (string)
    Current underwriting lifecycle status for the merchant.
    Example: pending

  - `results.seller_amount_approved` (integer)
    Merchant approved limit (MAL), when available.
    Example: 50000

  - `results.active_subscription` (object)

  - `results.active_subscription.id` (string)
    Example: sub_1234567890abcdef

  - `results.active_subscription.tier` (string)
    Example: trial

  - `results.document_ingestion` (object)

  - `results.document_ingestion.requested_count` (integer)
    Example: 2

  - `results.document_ingestion.queued_count` (integer)
    Example: 1

  - `results.document_ingestion.failed_count` (integer)
    Example: 1

  - `results.document_ingestion.results` (array)

  - `results.document_ingestion.results.document_id` (string)
    Example: md_1234567890abcdef

  - `results.document_ingestion.results.document_type` (string)
    Enum: "bank_statements", "financial_statements", "credit_references", "personal_guarantee", "other"

  - `results.document_ingestion.results.filename` (string)

  - `results.document_ingestion.results.download_url` (string)

  - `results.document_ingestion.results.status` (string)
    Enum: "queued", "failed"

  - `results.document_ingestion.results.error_code` (string)

  - `results.document_ingestion.results.error_message` (string)

  - `results.created_at` (string)
    Example: 2026-02-26T10:00:00.000Z

  - `results.updated_at` (string)
    Example: 2026-02-26T10:05:00.000Z

## Response 400 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Validation error

  - `error.type` (string)
    A short string, describing error type
    Enum: "validation_error"

  - `error.details` (array)

  - `error.details.path` (string)
    Path to the field failed validation
    Example: path.to.field

  - `error.details.message` (string)
    Detailed description of the error
    Example: `[field]` is required

## Response 401 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Invalid merchant credentials

  - `error.type` (string)
    A short string, describing error type
    Enum: "authentication_error"

## Response 429 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: Too many requests

  - `error.type` (string)
    A short string, describing error type
    Enum: "rate_limit_error"