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

# Create payout request

> Request a payout of a partner's earned commissions on their behalf

## Endpoint

```
POST https://api.partnero.com/v1/payout_requests
```

Creates a payout request for a partner, just as if they had requested it in the partner portal. The same program rules apply: the payout threshold, disabled payout requests, and EU self-billing.

The request is created with the status `requested` and `created_by: "api"`. You get the usual new payout request notification. To continue, [approve](/api-reference/payout-requests/approve) it.

## Request body

**Partner identification**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `partner.id` | string | Yes\* | Partner ID |
| `partner.key` | string | Yes\* | Any referral key belonging to the partner |
| `partner.email` | string | Yes\* | Partner's email address |

\*Provide at least one: `id`, `key` or `email`.

**Payout fields**

| Parameter | Type | Required | Description |
| - | - | - | - |
| `amount_units` | string | Yes | Currency to pay out, e.g. `usd`. The partner must have a payout available in this currency. |
| `gateway` | string | No | `paypal`, `wise`, `crypto` or `venmo`. Defaults to the partner's preferred payout method. |
| `payout_settings` | object | No | Payment details for this payout only (see below). Defaults to the partner's saved settings for the gateway. |
| `reward_ids` | array | No | Pay out only these commissions. Allowed only when commission selection is enabled for the program. |

The payout amount is always the partner's full available balance in `amount_units`, or the total of `reward_ids` if you send them. You can't set the amount directly.

**Payout settings fields**

`payout_settings` is a flat object with the fields of the gateway. Fields that don't belong to the gateway are ignored.

| Gateway | Fields |
| - | - |
| `paypal` | `username` (required, PayPal email), `name`, `address`, `tax_id` |
| `crypto` | `wallet_address` (required), `type`, `name` |
| `venmo` | `name` (required), `recipient_type` (`USER_HANDLE` by default, `EMAIL` or `PHONE`), and the matching `user_handle`, `email` or `phone` (required) |
| `wise` | Not supported. The partner's saved Wise bank details are always used, and `payout_settings` is ignored. |

## How the gateway and payment details are chosen

1. **Gateway**: the `gateway` you send, or else the partner's preferred payout method. If the partner has no preferred payout method, the request fails.
2. **Payment details**: `payout_settings` from the request, if given (not for Wise). Otherwise, the settings the partner saved for that gateway. You can use any gateway the partner has saved settings for, even if it isn't their preferred one.
3. **Wise**: the partner's saved bank details for their preferred bank currency are used.

If there are no payment details for the gateway, the request fails. Details you send are used only for this payout request. The partner's saved payout settings are never changed.

## Request

<Tabs>
  <Tab title="Preferred method">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/payout_requests' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "partner": {
          "id": "partner_123"
        },
        "amount_units": "usd"
      }'
    ```
  </Tab>

  <Tab title="PayPal with details">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/payout_requests' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "partner": {
          "id": "partner_123"
        },
        "amount_units": "usd",
        "gateway": "paypal",
        "payout_settings": {
          "username": "partner@example.com",
          "name": "Jane Doe",
          "address": "1 Main St, Vilnius",
          "tax_id": "LT123456789"
        }
      }'
    ```
  </Tab>

  <Tab title="Wise">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/payout_requests' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "partner": {
          "email": "partner@example.com"
        },
        "amount_units": "eur",
        "gateway": "wise"
      }'
    ```
  </Tab>

  <Tab title="Crypto">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/payout_requests' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "partner": {
          "key": "ref_123"
        },
        "amount_units": "usd",
        "gateway": "crypto",
        "payout_settings": {
          "type": "btc",
          "wallet_address": "bc1q..."
        }
      }'
    ```
  </Tab>

  <Tab title="Selected commissions">
    ```bash theme={null}
    curl --location 'https://api.partnero.com/v1/payout_requests' \
      --header 'Authorization: Bearer YOUR_API_KEY' \
      --header 'Content-Type: application/json' \
      --data '{
        "partner": {
          "id": "partner_123"
        },
        "amount_units": "usd",
        "reward_ids": [101, 102]
      }'
    ```
  </Tab>
</Tabs>

## Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "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"
    },
    "status": 1
  }
  ```
</ResponseExample>

See [the payout request object](/api-reference/payout-requests/overview#the-payout-request-object) for the response fields.

## Error responses

Errors return `{"status": 0, "message": "..."}`. Validation errors also include `errors`, keyed by field (for example `payout_settings.username`).

| Status | Error | Solution |
| - | - | - |
| 404 | Partner not found | Check the partner `id`, `key` or `email` is correct for this program |
| 422 | Validation error | Check required fields, `gateway`, and `payout_settings` for the gateway. This error is also returned when no payout is available in `amount_units`. |
| 422 | Partner is not active | Only active partners can request payouts |
| 422 | Payout requests are disabled for this program or partner. | Enable payout requests in the program or partner settings |
| 422 | Partner must complete tax & billing details before a payout can be requested. | The partner must complete their billing profile (EU self-billing programs) |
| 422 | Selecting specific commissions is not enabled for this program. | Remove `reward_ids`, or enable commission selection |
| 422 | Partner does not have a preferred payout gateway. | Send `gateway` |
| 422 | Partner must set payout settings for the "wise" payout gateway. | Send `payout_settings` (not for Wise), or ask the partner to save their payout settings |

<Tip>
  Retrying is safe. If the same request is sent twice at the same time, the second one sees the already-reduced balance and fails, so the partner's commissions can't be paid out twice.
</Tip>