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

# Update Payout

> Update a payout's status, payment method, or payment reference

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the payout to update
</ParamField>

## Body Parameters

<ParamField body="status" type="string" required>
  Update the payout status. Valid values: `pending`, `processing`, `completed`, `failed`, `cancelled`. Status transitions are validated:

  * `pending` → `processing`, `cancelled`
  * `processing` → `completed`, `failed`, `cancelled`
  * `failed` → `pending`, `cancelled`
  * `completed` → (cannot be changed)
  * `cancelled` → `pending`

  When status is set to `completed`, `processedAt` is automatically set and all associated commission transactions are marked as `paid`. Status changes may trigger webhook events (`payout.paid`, `payout.failed`).
</ParamField>

<ParamField body="paymentMethod" type="string">
  Update the payment method used for the payout. Maximum 50 characters.
</ParamField>

<ParamField body="paymentReference" type="string">
  Update the external payment reference (e.g., PayPal transaction ID, bank transfer reference). Maximum 255 characters.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Always `true` for successful responses
</ResponseField>

<ResponseField name="data" type="object">
  The updated payout object.

  <Expandable title="Data Object Properties">
    <ResponseField name="id" type="string">
      Unique identifier for the payout
    </ResponseField>

    <ResponseField name="affiliate_id" type="string">
      The affiliate ID who will receive this payout
    </ResponseField>

    <ResponseField name="invoice_number" type="number">
      Invoice number for this payout
    </ResponseField>

    <ResponseField name="amount" type="number">
      Total payout amount
    </ResponseField>

    <ResponseField name="status" type="string">
      Payout status: `pending`, `processing`, `completed`, `failed`, `cancelled`
    </ResponseField>

    <ResponseField name="payment_method" type="string | null">
      Payment method used
    </ResponseField>

    <ResponseField name="payment_reference" type="string | null">
      External payment reference
    </ResponseField>

    <ResponseField name="processed_at" type="string | null">
      ISO 8601 timestamp when processed
    </ResponseField>

    <ResponseField name="managed_payout" type="boolean">
      Whether this is a managed payout
    </ResponseField>

    <ResponseField name="affiliate" type="object | null">
      Affiliate info with `name` and `email`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X PUT "https://api.affonso.io/v1/payouts/pay_abc123" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "completed",
      "paymentMethod": "paypal",
      "paymentReference": "PAYPAL-TXN-123456"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "pay_abc123",
      "affiliateId": "aff_456def",
      "invoiceNumber": 1001,
      "amount": 150.00,
      "status": "completed",
      "paymentMethod": "paypal",
      "paymentReference": "PAYPAL-TXN-123456",
      "processedAt": "2024-01-25T14:30:00Z",
      "managedPayout": true,
      "affiliate": {
        "name": "John Doe",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-25T10:00:00Z",
      "updatedAt": "2024-01-25T14:30:00Z"
    }
  }
  ```
</ResponseExample>