Treatwell Booking Integration — Analysis

This document set analyses the end-to-end flow for booking creation and rescheduling through the Treatwell integration (tw-integration engine), with a focus on availability management and all failure modes that could reduce the booking success rate below 100%.

Scale context

Metric	Value
Active venues	~13 000
Bookings created / month	~600 000
Rescheduled bookings / month	~75 000
Peak throughput	~2 events / second

At 2 events/second a 1% failure rate translates to ~6 750 failed bookings per month.

Documents

Document	What it covers
01 — Booking Creation	Full call chain from HTTP request to committed appointment
02 — Reschedule	Full call chain for a reschedule, including the asymmetric deletion risk
03 — Availability Management	How availability matrices are built, served, and (not) invalidated
04 — Failure Modes & Recommendations	Consolidated risk register and prioritised fixes

Entry points

POST   /tw/booking              → BookingsController#create    → Treatwell::BookingService
PUT    /tw/booking/:ref/reschedule → BookingsController#reschedule → Treatwell::BookingRescheduleService
DELETE /tw/booking/:ref         → BookingsController#destroy   → Treatwell::BookingCancellationService
PUT    /tw/direct-booking/:id/reschedule → DirectBookingsController#reschedule → Treatwell::BookingRescheduleService

Both paths share:

• JWT authentication (TREATWELL_ISSUER)
• Entity change tracking disabled for performance
• Treatwell::BaseBooking for slot resolution
• Availabilities::FinderOverMatricesService for availability lookup