# List Merchant Documents

Returns document presence and validation lifecycle status for a specific sub-merchant.
This endpoint is metadata-only and does not return file bodies or signed retrieval URLs.
Supported query options:
- Pagination: `limit`, `page`
- Sorting: `sort`
- Field filters: `filter[field][eq]=value`

Supported filter fields:
- `document_type`
- `status`

Supported sort fields:
- `created_at`

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

Endpoint: GET /merchants/{merchant_id}/documents
Version: partners-v1
Security: bearerAuth, basicAuth

## Path parameters:

  - `merchant_id` (string, required)
    ID of the sub-merchant under your partner account.

## Query parameters:

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

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

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

Prefix with `-` for descending order.

  - `filter` (object)
    Filter merchant documents by type or validation status.

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

Supported filters:
- `filter[document_type][eq]=bank_statements`
- `filter[status][eq]=accepted`

## Response 200 fields (application/json):

  - `count` (integer)
    Example: 2

  - `page` (integer)
    Example: 1

  - `limit` (integer)
    Example: 25

  - `results` (array)

  - `results.id` (string)
    Example: md_1234567890abcdef

  - `results.merchant_id` (string)
    Example: mrc_1234567890abcdef

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

  - `results.status` (string)
    Current validation lifecycle status.
    Enum: "pending_upload", "uploaded_pending_validation", "accepted", "rejected", "failed"

  - `results.validation_reasons` (array)
    Validation reason codes/messages associated with the current status.
    Example: []

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

  - `results.validated_at` (string)
    Example: 2026-02-26T10:06:40.000Z

  - `results.object_key` (string)
    S3 object key reference used by validation/reconciliation flows.
    Example: merchant/mrc_123/document/md_1234567890abcdef/bank_statement_2026_01.pdf

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

  - `results.updated_at` (string)
    Example: 2026-02-26T10:06:40.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 404 fields (application/json):

  - `error` (object)

  - `error.message` (string)
    A short string, describing error details
    Example: [entity] not found

  - `error.type` (string)
    A short string, describing error type
    Enum: "not_found_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"