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

# Payout Events

> Webhook events for affiliate payouts and payments

Payout events track the payment lifecycle for affiliate commissions.

## Events

| Event            | Description                            |
| ---------------- | -------------------------------------- |
| `payout.created` | New payout is created for an affiliate |
| `payout.updated` | Payout is modified (universal event)   |
| `payout.paid`    | Payout is marked as completed          |
| `payout.failed`  | Payout fails                           |
| `payout.deleted` | Payout is deleted                      |

## Payout Status Values

| Status       | Description                         |
| ------------ | ----------------------------------- |
| `PENDING`    | Payout created, awaiting processing |
| `PROCESSING` | Payout is being processed           |
| `COMPLETED`  | Payout successfully completed       |
| `FAILED`     | Payout failed                       |

## Payload

<ResponseField name="id" type="string">
  Unique event identifier
</ResponseField>

<ResponseField name="type" type="string">
  Event type (e.g., `payout.paid`)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the event occurred
</ResponseField>

<ResponseField name="data" type="object">
  Event payload data.

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

    <ResponseField name="affiliateId" type="string">
      The affiliate receiving this payout
    </ResponseField>

    <ResponseField name="affiliateProgramId" type="string">
      The program this payout belongs to
    </ResponseField>

    <ResponseField name="invoiceNumber" type="number">
      Sequential invoice number for the payout
    </ResponseField>

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

    <ResponseField name="status" type="string">
      Payout status (see table above)
    </ResponseField>

    <ResponseField name="isManagedPayout" type="boolean">
      Whether this is an auto-managed payout
    </ResponseField>

    <ResponseField name="paidAt" type="string | null">
      ISO 8601 timestamp when paid
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Payloads

```json payout.created theme={null}
{
  "id": "evt_abc123",
  "type": "payout.created",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "payoutId": "pay_xyz789",
    "affiliateId": "aff_abc123",
    "affiliateProgramId": "prog_def456",
    "invoiceNumber": 1042,
    "amount": 250.00,
    "status": "PENDING",
    "isManagedPayout": false,
    "paidAt": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

```json payout.paid theme={null}
{
  "id": "evt_abc123",
  "type": "payout.paid",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "payoutId": "pay_xyz789",
    "affiliateId": "aff_abc123",
    "affiliateProgramId": "prog_def456",
    "invoiceNumber": 1042,
    "amount": 250.00,
    "status": "COMPLETED",
    "isManagedPayout": true,
    "paidAt": "2024-01-15T14:00:00.000Z",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T14:00:00.000Z"
  }
}
```

```json payout.failed theme={null}
{
  "id": "evt_abc123",
  "type": "payout.failed",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "payoutId": "pay_xyz789",
    "affiliateId": "aff_abc123",
    "affiliateProgramId": "prog_def456",
    "invoiceNumber": 1042,
    "amount": 250.00,
    "status": "FAILED",
    "isManagedPayout": true,
    "paidAt": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T14:00:00.000Z"
  }
}
```