> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affonso.io/llms.txt
> Use this file to discover all available pages before exploring further.

# List Payouts

> Get a paginated list of all payouts with optional filtering

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination. Must be a positive integer.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of results per page. Maximum value is 200. Default is 50.
</ParamField>

<ParamField query="status" type="string">
  Filter payouts by status. Valid values: `pending`, `processing`, `completed`, `failed`, `cancelled`.
</ParamField>

<ParamField query="affiliateId" type="string">
  Filter payouts by affiliate ID. Only returns payouts for the specified affiliate.
</ParamField>

<ParamField query="sort" type="string">
  Sort field and direction in the format `field:direction`. Valid fields: `createdAt`, `updatedAt`, `amount`, `processedAt`. Valid directions: `asc`, `desc`. Example: `createdAt:desc`.
</ParamField>

<ParamField query="dateFrom" type="string">
  Filter payouts created on or after this date. ISO 8601 date format (e.g., `2024-01-01`).
</ParamField>

<ParamField query="dateTo" type="string">
  Filter payouts created on or before this date. ISO 8601 date format (e.g., `2024-12-31`).
</ParamField>

## Response

The response includes a paginated list of payouts and pagination metadata.

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="array">
  Array of payout objects.

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique payout identifier
    </ResponseField>

    <ResponseField name="affiliateId" type="string">
      Affiliate ID
    </ResponseField>

    <ResponseField name="invoiceNumber" type="number">
      Invoice number
    </ResponseField>

    <ResponseField name="amount" type="number">
      Payout amount
    </ResponseField>

    <ResponseField name="status" type="string">
      Payout status (lowercase): `pending`, `processing`, `completed`, `failed`, `cancelled`
    </ResponseField>

    <ResponseField name="paymentMethod" type="string | null">
      Payment method used
    </ResponseField>

    <ResponseField name="paymentReference" type="string | null">
      External payment reference
    </ResponseField>

    <ResponseField name="processedAt" type="string | null">
      ISO 8601 timestamp when processed
    </ResponseField>

    <ResponseField name="managedPayout" type="boolean">
      Whether this is a managed payout
    </ResponseField>

    <ResponseField name="affiliate" type="object | null">
      Affiliate information (name, email)
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 last update timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata object containing:

  * `page` (integer): Current page number
  * `limit` (integer): Number of results per page
  * `total` (integer): Total number of payouts matching the filters
  * `totalPages` (integer): Total number of pages
  * `hasNextPage` (boolean): Whether there is a next page
  * `hasPrevPage` (boolean): Whether there is a previous page
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.affonso.io/v1/payouts?limit=10&status=pending" \
    -H "Authorization: Bearer sk_live_your_api_key"
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "pay_abc123",
        "affiliateId": "aff_456def",
        "invoiceNumber": 1001,
        "amount": 150.00,
        "status": "pending",
        "paymentMethod": "paypal",
        "paymentReference": null,
        "processedAt": null,
        "managedPayout": true,
        "affiliate": {
          "name": "John Doe",
          "email": "john@example.com"
        },
        "createdAt": "2024-01-25T10:00:00Z",
        "updatedAt": "2024-01-25T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 15,
      "totalPages": 2,
      "hasNextPage": true,
      "hasPrevPage": false
    }
  }
  ```
</ResponseExample>