> ## 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.

# Payout Summary

> Get a high-level summary of payout totals and the next scheduled payout

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

## Overview

Return a high-level summary of the vendor's payout totals, including the most recent payout, the next scheduled payout, and aggregate amounts. Useful for building a payouts dashboard.

### Use Cases

* **Payouts dashboard** — Show "Total received", "Pending", and "Next payout" cards
* **Financial overview** — Give vendors a snapshot of their earnings at a glance
* **Payout scheduling visibility** — Display when the next automated payout will run

## 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="dateMin" type="string">
  ISO 8601 lower bound on the date range.
</ParamField>

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

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "totalReceived": 12500.00,
    "totalPending": 3200.00,
    "totalScheduled": 1500.00,
    "currency": "USD",
    "shopTimezone": "America/New_York",
    "previousPayout": {
      "amount": 5000.00,
      "status": "paid",
      "date": "2026-05-01T00:00:00Z",
      "latestBatchId": "507f1f77bcf86cd799439055"
    },
    "nextPayout": {
      "amount": 1500.00,
      "status": "scheduled",
      "estimatedDate": "2026-06-01T00:00:00Z",
      "type": "automated",
      "startDate": "2026-05-01T00:00:00Z",
      "endDate": "2026-05-31T23:59:59Z"
    },
    "itemCount": 156
  }
}
```

### 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/summary?dateMin=2026-01-01T00:00:00Z&dateMax=2026-05-31T23:59:59Z" \
  -H "x-access-token: YOUR_VENDOR_JWT"
```