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

# List Payouts

> Retrieve vendor-scoped payout transactions with cursor-based pagination

<Note>
  **V2 Alpha** — This endpoint is part of the V2 API preview. Breaking changes may occur.
</Note>

## Overview

Retrieve a paginated list of payout transactions for the authenticated vendor. Results include transaction status, amounts, processing dates, and item counts. Only payouts belonging to the vendor are returned.

<Note>
  **Vendor Token Required** — This endpoint requires a vendor-scoped JWT token. Merchant tokens will receive a 403 error.
</Note>

### Use Cases

* **Payout dashboard** — Display pending and completed payouts in a vendor portal
* **Accounting reconciliation** — Export payout data for bookkeeping
* **Payment tracking** — Monitor payout statuses and amounts

## Query Parameters

<ParamField query="status" type="string">
  Filter by payout status. One of: `pending`, `paid`, `failed`, `cancelled`.
</ParamField>

<ParamField query="dateMin" type="string">
  Filter by date (minimum, ISO 8601). Example: `2024-01-01T00:00:00Z`.
</ParamField>

<ParamField query="dateMax" type="string">
  Filter by date (maximum, ISO 8601).
</ParamField>

<ParamField query="first" type="integer">
  Number of items to return, forward pagination (1-100).
</ParamField>

<ParamField query="after" type="string">
  Cursor for forward pagination.
</ParamField>

<ParamField query="last" type="integer">
  Number of items to return, backward pagination (1-100).
</ParamField>

<ParamField query="before" type="string">
  Cursor for backward pagination.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "transactions": [
      {
        "_id": "507f1f77bcf86cd799439050",
        "transactionId": "TXN-2024-001042",
        "status": "paid",
        "amount": 1250.75,
        "currency": "GBP",
        "itemCount": 12,
        "processedAt": "2024-06-20T14:00:00.000Z",
        "createdAt": "2024-06-15T10:30:00.000Z"
      },
      {
        "_id": "507f1f77bcf86cd799439051",
        "transactionId": "TXN-2024-001038",
        "status": "pending",
        "amount": 840.50,
        "currency": "GBP",
        "itemCount": 8,
        "processedAt": null,
        "createdAt": "2024-06-18T09:15:00.000Z"
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTA1MCJ9",
      "endCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTA1MSJ9",
      "totalCount": 25
    }
  }
}
```

## Example

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/payouts?status=pending&first=20" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```

### More Examples

**Filter unpaid payouts**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/payouts?first=20&status=unpaid&fulfillment=fulfilled" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```

**Payouts in date range**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/payouts?first=50&dateMin=2026-04-01T00:00:00Z&dateMax=2026-04-30T23:59:59Z" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```