Booking Lifecycle

Every booking moves through a defined set of states. Understanding this is key to building on AvailEngine.

State Machine

              ┌──────────┐
              │ pending  │  ← Created. Deposit required but unpaid.
              └────┬─────┘
                   │ deposit paid
                   ▼
              ┌──────────┐
              │confirmed │  ← Slot locked. Customer expected.
              └────┬─────┘
                   │
        ┌──────────┼──────────┐
        │          │          │
        ▼          ▼          ▼
  ┌─────────┐ ┌────────┐ ┌────────┐
  │checked_in│ │no_show │ │cancelled│
  └────┬────┘ └────────┘ └────────┘
       │
       ▼
  ┌──────────┐
  │completed │
  └──────────┘

Creating a Booking

curl -X POST https://api.availengine.com/v1/bookings/ \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "uuid",
    "booking_date": "2026-05-15",
    "start_time": "14:00",
    "capacity": 1,
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane@example.com",
    "phone": "+301234567890"
  }'

With Deposit

If the business has deposits enabled, the response also includes stripe_client_secret and deposit_type:

{
  "booking": {
    "id": "uuid",
    "status": "pending",
    "confirmation_code": "AV-ABC123",
    "booking_date": "2026-05-15",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "capacity": 1
  },
  "stripe_client_secret": "pi_xxx_secret_yyy",
  "deposit_type": "charge"
}

The customer pays using Stripe Elements or Checkout. On success, the booking auto-transitions to confirmed.

Without Deposit

{
  "booking": {
    "id": "uuid",
    "status": "confirmed",
    "confirmation_code": "AV-ABC123",
    "booking_date": "2026-05-15",
    "start_time": "14:00:00",
    "end_time": "15:00:00",
    "capacity": 1
  }
}

Updating a Booking

curl -X PATCH https://api.availengine.com/v1/manage/bookings/{booking_id} \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "checked_in"
  }'

What Can Change

Field	Who	When
status	Staff	Any time
resource_id	Staff	Before check-in
capacity	Staff	Before check-in
staff_notes	Staff	Any time
customer_notes	Staff/API	Before completion

Cancelling

curl -X PATCH https://api.availengine.com/v1/manage/bookings/{booking_id} \
  -H "Authorization: Bearer avail_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled",
    "cancellation_reason": "Customer request"
  }'

If a deposit was held:

• Within cancellation_cutoff_hours → deposit is released (refunded)
• After cutoff → deposit is captured (charged)

No-Show Handling

curl -X POST https://api.availengine.com/v1/manage/bookings/{booking_id}/no-show \
  -H "Authorization: Bearer avail_live_YOUR_KEY"

This captures the deposit and marks the booking as no_show.

Webhooks

Every state change fires a webhook to your registered endpoints:

Event	Fires when
booking.created	New booking (pending or confirmed)
booking.confirmed	Deposit paid, booking confirmed
booking.checked_in	Customer arrives
booking.completed	Service done
booking.cancelled	Booking cancelled
booking.no_show	Customer didn't show
deposit.paid	Deposit payment successful
deposit.captured	Deposit charged (no-show)
deposit.released	Deposit refunded

Learn about webhook verification →