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

# Transaction Events

> Webhook events for sales, commissions, and refunds

Transaction events track sales and commission lifecycle.

<Info>
  `transaction.created` is emitted for both manual commission creation and
  automatic server-side conversion tracking via
  <a href="/api-reference/endpoint/conversions/create">POST /conversions</a>.
  Refunds triggered through the
  <a href="/api-reference/endpoint/conversions/refund">Refund Conversion endpoint</a>
  emit `transaction.updated` for partial refunds and `transaction.rejected` for
  full refunds.
  If a conversion does not create an affiliate earning, the commission-related
  fields in the webhook payload can be `null`.
</Info>

## Events

| Event                  | Description                                  |
| ---------------------- | -------------------------------------------- |
| `transaction.created`  | New transaction (sale) is recorded           |
| `transaction.updated`  | Transaction is modified (universal event)    |
| `transaction.approved` | Commission is approved and ready for payment |
| `transaction.paid`     | Commission is paid to the affiliate          |
| `transaction.rejected` | Commission is declined or refunded           |
| `transaction.deleted`  | Transaction is deleted                       |

## Sale Status Values

| Status             | Description                  |
| ------------------ | ---------------------------- |
| `OPEN`             | Transaction pending payment  |
| `COMPLETE`         | Payment successful           |
| `TRIALING`         | Subscription in trial period |
| `FAILED`           | Payment failed               |
| `REFUNDED`         | Full refund processed        |
| `PARTIAL_REFUNDED` | Partial refund processed     |

## Commission Status Values

| Status                    | Description                       |
| ------------------------- | --------------------------------- |
| `PENDING`                 | Awaiting hold period to expire    |
| `PENDING_MANUAL_APPROVAL` | Requires manual approval          |
| `READY_FOR_PAYMENT`       | Approved, included in next payout |
| `PROCESSING_PAYOUT`       | Assigned to an active payout      |
| `PAID`                    | Commission has been paid          |
| `DECLINED`                | Manually declined                 |
| `REFUNDED`                | Declined due to refund            |
| `DISPUTE`                 | Under dispute investigation       |

## Payload

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

<ResponseField name="type" type="string">
  Event type (e.g., `transaction.created`)
</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="transactionId" type="string">
      Unique identifier for the transaction
    </ResponseField>

    <ResponseField name="referralId" type="string">
      The referral this transaction belongs to
    </ResponseField>

    <ResponseField name="affiliateId" type="string">
      The affiliate who earned this commission
    </ResponseField>

    <ResponseField name="saleAmount" type="number">
      The sale amount (in program currency)
    </ResponseField>

    <ResponseField name="saleCurrency" type="string">
      Currency code (e.g., `USD`)
    </ResponseField>

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

    <ResponseField name="commissionAmount" type="number">
      Commission amount earned
    </ResponseField>

    <ResponseField name="commissionCurrency" type="string">
      Commission currency code
    </ResponseField>

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

    <ResponseField name="incentiveType" type="string">
      Type: `COMMISSION` or `BONUS`
    </ResponseField>

    <ResponseField name="holdPeriodDays" type="number | null">
      Days commission was held before approval
    </ResponseField>

    <ResponseField name="invoiceId" type="string | null">
      Associated payout invoice ID
    </ResponseField>

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

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

## Example Payloads

```json transaction.created theme={null}
{
  "id": "evt_abc123",
  "type": "transaction.created",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "transactionId": "txn_xyz789",
    "referralId": "ref_abc123",
    "affiliateId": "aff_def456",
    "saleAmount": 99.00,
    "saleCurrency": "USD",
    "saleStatus": "COMPLETE",
    "commissionAmount": 29.70,
    "commissionCurrency": "USD",
    "commissionStatus": "PENDING",
    "incentiveType": "COMMISSION",
    "holdPeriodDays": 30,
    "invoiceId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

```json transaction.approved theme={null}
{
  "id": "evt_abc123",
  "type": "transaction.approved",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "transactionId": "txn_xyz789",
    "referralId": "ref_abc123",
    "affiliateId": "aff_def456",
    "saleAmount": 99.00,
    "saleCurrency": "USD",
    "saleStatus": "COMPLETE",
    "commissionAmount": 29.70,
    "commissionCurrency": "USD",
    "commissionStatus": "READY_FOR_PAYMENT",
    "incentiveType": "COMMISSION",
    "holdPeriodDays": 30,
    "invoiceId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-02-14T10:30:00.000Z"
  }
}
```

```json transaction.paid theme={null}
{
  "id": "evt_abc123",
  "type": "transaction.paid",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "transactionId": "txn_xyz789",
    "referralId": "ref_abc123",
    "affiliateId": "aff_def456",
    "saleAmount": 99.00,
    "saleCurrency": "USD",
    "saleStatus": "COMPLETE",
    "commissionAmount": 29.70,
    "commissionCurrency": "USD",
    "commissionStatus": "PAID",
    "incentiveType": "COMMISSION",
    "holdPeriodDays": 30,
    "invoiceId": "inv_123",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-02-28T10:30:00.000Z"
  }
}
```

```json transaction.rejected theme={null}
{
  "id": "evt_abc123",
  "type": "transaction.rejected",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "data": {
    "transactionId": "txn_xyz789",
    "referralId": "ref_abc123",
    "affiliateId": "aff_def456",
    "saleAmount": 0,
    "saleCurrency": "USD",
    "saleStatus": "REFUNDED",
    "commissionAmount": 0,
    "commissionCurrency": "USD",
    "commissionStatus": "REFUNDED",
    "incentiveType": "COMMISSION",
    "holdPeriodDays": null,
    "invoiceId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-20T14:00:00.000Z"
  }
}
```