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

# Payout requests API overview

> Create, review, approve and mark partner payout requests as paid from your own system.

A payout request asks you to pay a partner the commissions they've earned. Partners usually create them in the partner portal, and Partnero can create them automatically. The payout requests API lets you do the same from your own system, and move a request through review until it's paid.

<Note>
  Affiliate programs only. Call these endpoints **server-side**, because they need your secret API key.
</Note>

## Key concepts

* **Payout request ID**: a numeric `id` returned when the request is created. Use it to get, approve or mark the request as paid.
* **Gateway**: how the partner is paid: `paypal`, `wise`, `crypto` or `venmo`.
* **Payout settings**: the partner's payment details for the gateway (for example their PayPal email). You can send them when [creating](/api-reference/payout-requests/create) a payout request.
* **Status**: where the request is in its lifecycle (see [Status values](#status-values)).

## Available endpoints

<CardGroup cols={2}>
  <Card title="List and search" icon="list" href="/api-reference/payout-requests/list">
    Retrieve payout requests, filtered by partner, status or currency
  </Card>

  <Card title="Get payout request" icon="receipt" href="/api-reference/payout-requests/get">
    Get a single payout request by ID
  </Card>

  <Card title="Create payout request" icon="plus" href="/api-reference/payout-requests/create">
    Request a payout on a partner's behalf
  </Card>

  <Card title="Approve" icon="check" href="/api-reference/payout-requests/approve">
    Approve a payout request
  </Card>

  <Card title="Mark as paid" icon="money-bill-transfer" href="/api-reference/payout-requests/mark-as-paid">
    Record that the payout has been paid
  </Card>
</CardGroup>

## Lifecycle

1. **Create**: the request starts as `requested`. Partner portal requests and requests from automations appear here too.
2. **Approve**: the status becomes `approved` and the partner gets the approval email. If automated payouts are enabled, the payout may then be scheduled, and the status changes to one of the `*_scheduled` values.
3. **Mark as paid**: once you've paid the partner outside Partnero, the status becomes `finished`. The payout's commissions are marked as paid and the partner gets the "payout sent" email.

## The payout request object

```json theme={null}
{
  "id": 555,
  "partner": "partner_123",
  "status": "requested",
  "amount": 200.0,
  "amount_units": "usd",
  "payout_gateway": "paypal",
  "created_by": "api",
  "created_at": "2026-09-29T10:15:00.000000Z",
  "updated_at": "2026-09-29T10:15:00.000000Z"
}
```

| Field | Type | Description |
| - | - | - |
| `id` | integer | Payout request ID |
| `partner` | string | Partner ID |
| `status` | string | Current status (see [Status values](#status-values)) |
| `amount` | number | Payout amount |
| `amount_units` | string | Payout currency, in lowercase |
| `payout_gateway` | string | `paypal`, `wise`, `crypto` or `venmo` |
| `created_by` | string | Where the request came from: `api`, `partner` (partner portal), `automated_partner_payouts` and so on |
| `created_at` | string | ISO 8601 timestamp |
| `updated_at` | string | ISO 8601 timestamp |

## Status values

| Status | Description |
| - | - |
| `requested` | Created and waiting for review |
| `resubmit_requested` | You asked the partner to resubmit |
| `resubmitted` | The partner resubmitted |
| `approved` | Approved and waiting to be paid |
| `approved_auto_scheduled` | Approved and scheduled for an automated payout |
| `mass_approved_scheduled` | Approved and scheduled for a mass payout |
| `intermediary_approved_scheduled` | Approved and scheduled to be paid through Partnero's Wise account |
| `failed_auto_scheduled` | The automated payout failed |
| `finished` | Paid |
| `rejected` | Rejected |

<Tip>
  Create, approve and mark as paid are safe to retry. Identical requests sent at the same time are processed one after another, so the same commissions can't be paid out twice.
</Tip>