Event catalog - Zahlo Merchant Developer Docs

Subscribe to the smallest event set that supports your business flow. Common event families cover checkout sessions, payments, transactions, refunds, subscriptions, invoices, and customer actions.

Event envelope

{
  "id": "evt_demo_1001",
  "type": "payment.confirmed",
  "createdAt": "2026-09-02T12:00:00Z",
  "data": { "object": { "id": "pay_demo_1001", "status": "confirmed" } }
}

Treat id as the deduplication key. Treat type as a routing key and data.object.id as the resource to retrieve when your handler needs authoritative details.

Fulfillment mapping

Event	Typical action
`payment.confirmed`	Fulfill the matching order once
`payment.failed`	Keep the order pending and show recovery
`refund.succeeded`	Record the refund and notify the customer
`invoice.paid`	Grant or retain subscription access
`invoice.payment_failed`	Start dunning and keep access policy explicit
`subscription.cancelled`	Schedule or apply entitlement removal

Verify the signature over the raw body, insert the event ID before effects, acknowledge promptly, and queue slow work. Retrieve the resource when event data is incomplete or stale.