---
title: "Booking Lifecycle Event Model"
description: "Design travel-booking state around create, confirm, modify, cancel, fail and reconcile events with explicit ordering and idempotency."
slug: "booking-lifecycle-event-model"
translationKey: "architecture-booking-lifecycle-event"
locale: "en"
type: "guide"
category: "architecture"
tags: ["booking","event","lifecycle","reconciliation","idempotency"]
publishedAt: "2026-09-26"
updatedAt: "2026-09-26"
reviewedAt: "2026-09-26"
---

A booking lifecycle model should preserve **which events occurred, in what order and from which evidence current state was derived**, rather than reducing the reservation to one mutable status field.

## Production scenario

A create request times out while the supplier may have created the booking. A CONFIRMED webhook later arrives, followed by cancellation and refund events. One status field loses the audit trail.

## Architecture flow

```text
Booking Attempt
 -> CREATE_REQUESTED
 -> provider call
 -> CREATED / UNKNOWN / FAILED
 -> CONFIRMED
 -> MODIFIED?
 -> CANCEL_REQUESTED?
 -> CANCELLED?
 -> REFUND/SETTLEMENT?
 -> RECONCILED
```

## Key entities

Use Booking, BookingAttempt, BookingEvent, ProviderBookingReference, PaymentReference and ReconciliationRecord.

## Event shape

A useful event stores event ID, booking ID, event type, provider, provider reference, occurred/received timestamps and source such as API response, webhook or reconciliation.

## State derivation

Materialize current booking state from event history. Not every incoming event should be allowed to produce every transition.

Out-of-order events require explicit handling.

## Idempotency

Webhook delivery can repeat. Deduplicate using provider event IDs or deterministic event keys before applying state changes.

## Unknown state

UNKNOWN should be a first-class state after ambiguous timeouts. Marking it FAILED too early can cause duplicate bookings.

Resolve UNKNOWN through lookup and reconciliation.

## Separate payment lifecycle

Payment authorization does not prove booking confirmation. Maintain separate booking and payment state machines and reconcile them explicitly.

## Failure modes

Common failures include duplicate webhooks, out-of-order events, provider-reference changes, payment/booking divergence, premature cancellation state and duplicate creates after retry.

## Concurrency

Protect state materialization with event versions, sequences or optimistic concurrency. Parallel consumers must not apply transitions nondeterministically.

## Observability

Track unknown-booking age, duplicate/out-of-order events, booking/payment divergence, reconciliation latency and invalid transitions.

## Alternatives

For a simple low-volume single-provider system, an event table plus materialized status may be enough. Full event sourcing is justified only when replay/audit requirements warrant the complexity.

## Production checklist

Use immutable events, explicit transition rules, idempotency, ordering/version strategy, UNKNOWN state, separate payment lifecycle, reconciliation jobs, audit trails and replay tooling.