> ## 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 Payout Transactions

> List payout transactions with cursor pagination and filters

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

## Overview

Return a paginated list of payout transactions for the authenticated vendor. Uses cursor-based pagination for stable results when data changes between pages.

### Use Cases

* **Payout history table** — Show a list of past payouts with status and amounts
* **Transaction lookup** — Search for a specific payout by transaction ID or date
* **Reconciliation** — Cross-reference payouts with bank deposits

## Headers

<ParamField header="x-access-token" type="string" required>
  A valid vendor JWT. Requires `payouts:read` scope.
</ParamField>

## Query Parameters

<ParamField query="vendorId" type="string">
  Filter by vendor ID (24-character hex string). Defaults to the authenticated vendor.
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `pending` · `paid` · `failed` · `cancelled`.
</ParamField>

<ParamField query="dateMin" type="string">
  ISO 8601 lower bound on transaction date.
</ParamField>

<ParamField query="dateMax" type="string">
  ISO 8601 upper bound on transaction date.
</ParamField>

<ParamField query="search" type="string">
  Free-text search (max 200 characters). Searches transaction IDs and order references.
</ParamField>

<ParamField query="first" type="integer">
  Number of records to return from the start of the result set (forward pagination).
</ParamField>

<ParamField query="after" type="string">
  Cursor for forward pagination. Use the `endCursor` value from a previous response.
</ParamField>

<ParamField query="last" type="integer">
  Number of records to return from the end of the result set (backward pagination).
</ParamField>

<ParamField query="before" type="string">
  Cursor for backward pagination. Use the `startCursor` value from a previous response.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "edges": [
      {
        "node": {
          "_id": "664a1b2c3d4e5f6a7b8c9d20",
          "processedAt": "2026-05-01T12:00:00Z",
          "status": "paid",
          "transactionId": "txn_1PqR2sT3uV4wX5yZ",
          "itemCount": 12,
          "amount": 5000.00,
          "createdAt": "2026-04-30T18:00:00Z"
        },
        "cursor": "NjY0YTFiMmMzZDRlNWY2YTdiOGM5ZDIw"
      },
      {
        "node": {
          "_id": "664a1b2c3d4e5f6a7b8c9d21",
          "processedAt": "2026-04-01T12:00:00Z",
          "status": "paid",
          "transactionId": "txn_6AbC7dEf8gHi9jKl",
          "itemCount": 8,
          "amount": 3200.00,
          "createdAt": "2026-03-31T18:00:00Z"
        },
        "cursor": "NjY0YTFiMmMzZDRlNWY2YTdiOGM5ZDIx"
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "NjY0YTFiMmMzZDRlNWY2YTdiOGM5ZDIw",
      "endCursor": "NjY0YTFiMmMzZDRlNWY2YTdiOGM5ZDIx"
    }
  }
}
```

### Error Responses

```json 401 theme={null}
{ "success": false, "error": { "message": "Invalid or expired token" } }
```

```json 403 theme={null}
{ "success": false, "error": { "message": "Insufficient scope", "code": "FORBIDDEN" } }
```

## Example

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

### More Examples

**Filter paid transactions**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/payouts/transactions?first=20&status=paid&dateMin=2026-01-01T00:00:00Z" \
  -H "x-access-token: YOUR_VENDOR_JWT"
```