Event reference

Every event spuke 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 spuke 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, spuke 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

{
  "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.