# Event reference

Every event Southbill can send, with the payload shape.

# Event reference

## Checkout Sessions

| Event | When |
|---|---|
| `checkout.session.completed` | Buyer completed payment successfully. |
| `checkout.session.async_payment_succeeded` | Async method (SEPA, Klarna) cleared. |
| `checkout.session.async_payment_pending` | Async payment awaiting clearing. |
| `checkout.session.async_payment_failed` | Async payment failed after auth. |
| `checkout.session.expired` | Session was not paid within its window. |
| `checkout.session.canceled` | Merchant or buyer cancelled the session. |

## Payments & refunds

| Event | When |
|---|---|
| `payment.succeeded` | Payment captured. |
| `payment.failed` | Attempt failed. |
| `charge.refunded` | Full or partial refund issued. |

## Disputes

| Event | When |
|---|---|
| `charge.dispute.created` | Chargeback opened. Status: `needs_response`. |
| `charge.dispute.updated` | Evidence uploaded or Southbill changed status. |
| `charge.dispute.closed` | Case closed. Payload includes `outcome: won \| lost \| warning_closed`. |

## Invoices

| Event | When |
|---|---|
| `invoice.finalized` | Invoice sent to customer. |
| `invoice.paid` | Customer paid. |
| `invoice.payment_succeeded` | Renewal charge for a subscription succeeded. |
| `invoice.payment_failed` | Payment attempt on the invoice failed. Advances dunning. |
| `invoice.voided` | Merchant voided the invoice. |

## Subscriptions

| Event | When |
|---|---|
| `customer.subscription.created` | Subscription created (usually `incomplete` until first payment). |
| `customer.subscription.updated` | Status, price, quantity, or `cancel_at_period_end` changed. |
| `customer.subscription.deleted` | Subscription ended (immediately or at period end). |
| `customer.subscription.trial_will_end` | Fires 3 days before a trial ends. |
| `customer.subscription.paused` | Collection was paused. |
| `customer.subscription.resumed` | Collection resumed after a pause. |

### Dunning stages

When a renewal fails, Southbill advances the subscription through three dunning stages before giving up. Each stage triggers `invoice.payment_failed` with a `dunning_stage` in `metadata`:

| Stage | Trigger | Merchant action |
|---|---|---|
| `notice` | 1st failure | Notify the customer, update payment method. |
| `warning` | 2nd failure | Second reminder. Subscription becomes `past_due`. |
| `final` | 3rd failure | Final notice. Subscription moves to `unpaid` if retries are exhausted. |

## Payouts

| Event | When |
|---|---|
| `payout.paid` | Bank payout landed. |
| `payout.failed` | Bank payout was rejected — investigate bank details. |

## Sample payload

```json
{
  "id": "evt_01H…",
  "object": "event",
  "type": "checkout.session.completed",
  "created": 1735689600,
  "livemode": true,
  "data": {
    "object": {
      "id": "cs_01H…",
      "object": "checkout.session",
      "amount": 4990,
      "currency": "eur",
      "status": "complete",
      "reference": "ORDER-12345",
      "customer_name": "Jane Doe",
      "customer_email": "jane@example.com",
      "payment_method": "card",
      "metadata": {}
    }
  }
}
```

The resource always lives at `data.object` — its shape mirrors the object created by the corresponding API endpoint.