# Bookings - Waitlist

Booking waitlist management

## GET /api/v1/booking-waitlist

List waitlist

List waitlist entries

**Permissions:** 🔵 `booking_waitlist.read`

Query parameters:
- `locationId` (number, optional) — Filter by location ID
- `status` ("waiting" | "notified" | "converted" | "expired" | "removed", optional) — Waitlist entry status
- `requestedDate` (string, optional) — Filter by requested date
- `page` (number, optional) — Page number
- `limit` (number, optional) — Items per page

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    entries: Array<{
        id: string // uuid
        locationId: number
        userId: number
        requestedDate: string // date
        preferredStartTime?: string | null
        preferredEndTime?: string | null
        partySize: number
        status: "waiting" | "notified" | "converted" | "expired" | "removed"
        convertedBookingId?: string | null // uuid
        expiresAt?: string | null // date-time
        notifiedAt?: string | null // date-time
        createdAt: string // date-time
        updatedAt: string // date-time
        userName?: string | null
        userEmail?: string | null
        userPhone?: string | null
      }>
    pagination: {
      page: number
      limit: number
      total: number
      totalPages: number
    }
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/booking-waitlist

Add to waitlist

Add a guest to the waitlist

**Permissions:** ⚪ `booking_waitlist.manage`

Request body:

```ts
{
  locationId: number
  userId: number
  requestedDate: string // date
  partySize: number
  preferredStartTime?: string
  preferredEndTime?: string
}
```

Response 201 — Default Response

```ts
{
  status: "success"
  data: {
    id: string // uuid
    locationId: number
    userId: number
    requestedDate: string // date
    preferredStartTime?: string | null
    preferredEndTime?: string | null
    partySize: number
    status: "waiting" | "notified" | "converted" | "expired" | "removed"
    convertedBookingId?: string | null // uuid
    expiresAt?: string | null // date-time
    notifiedAt?: string | null // date-time
    createdAt: string // date-time
    updatedAt: string // date-time
    userName?: string | null
    userEmail?: string | null
    userPhone?: string | null
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## DELETE /api/v1/booking-waitlist/{id}

Remove from waitlist

Remove a guest from the waitlist

**Permissions:** ⚪ `booking_waitlist.manage`

Path parameters:
- `id` (string, required) — Waitlist entry ID

Response 200 — Default Response

```ts
{
  status?: "success"
  data?: {
    deleted?: boolean
  }
  meta?: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/booking-waitlist/{id}/convert

Convert waitlist to booking

Convert a waitlist entry to a booking

**Permissions:** ⚪ `booking_waitlist.manage`

Path parameters:
- `id` (string, required) — Waitlist entry ID

Request body:

```ts
{
  tableId?: string // uuid
  startTime: string
  endTime: string
}
```

Response 201 — Default Response

```ts
{
  status: "success"
  data: {
    customFields?: Array<{
        fieldId?: string
        key?: string
        label?: string
        group?: string
        type?: string
        displayValue?: string
        value?: unknown // The stored value; its JSON type follows the field type
        version?: integer
        status?: string
      }>
    metadata?: {
      customFields?: Record<string, unknown>
    } | null
    id: string // uuid
    locationId: number
    tableId?: string | null // uuid
    bookingDate: string // date
    startTime: string
    endTime: string
    timezone: string
    primaryUserId?: number | null
    guestCount: number
    occasion?: "none" | "birthday" | "anniversary" | "business" | "date" | "celebration" | "other"
    specialRequests?: string | null
    internalNotes?: string | null
    notes?: Array<{
        uuid: string // uuid
        note: string
        sortOrder: number
        createdByRetailerUserId?: number | null
        updatedByRetailerUserId?: number | null
        createdAt: string // date-time
        updatedAt: string // date-time
      }>
    status: "pending" | "confirmed" | "checked_in" | "seated" | "completed" | "cancelled" | "no_show"
    paymentType?: "none" | "deposit" | "full_prepayment"
    depositAmountCents?: number | null
    purchaseId?: number | null
    confirmationCode: string
    bookingSource?: "direct" | "website" | "app" | "phone" | "walkin" | "third_party"
    estimatedRevenueCents?: number | null
    guestName?: string | null
    guestEmail?: string | null
    guestPhone?: string | null
    createdAt: string // date-time
    updatedAt: string // date-time
    confirmedAt?: string | null // date-time
    seatedAt?: string | null // date-time
    completedAt?: string | null // date-time
    cancelledAt?: string | null // date-time
    tabId?: string | null
    defaultTabStrategy: "single" | "per_resource"
    resources: Array<{
        qrCodeId: string // uuid
        isPrimary: boolean
        position: integer
      }>
    userName?: string | null
    userEmail?: string | null
    userPhone?: string | null
    tableName?: string | null
    location?: {
      id?: number
      name?: string | null
      city?: string | null
      latitude?: number | null
      longitude?: number | null
      logoImageUrl?: string | null
    } | null
    attribution?: {
      firstTouch?: {
        capturedAt: string // date-time
        utmSource?: string
        utmMedium?: string
        utmCampaign?: string
        utmContent?: string
        utmTerm?: string
        referrer?: string
        landingPage?: string
      }
      bookingTouch?: {
        capturedAt: string // date-time
        utmSource?: string
        utmMedium?: string
        utmCampaign?: string
        utmContent?: string
        utmTerm?: string
        referrer?: string
        landingPage?: string
      }
      reportedSource?: string
      recordedAt: string // date-time
    } | null
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```

## POST /api/v1/booking-waitlist/{id}/notify

Notify waitlist

Notify a waitlist entry of available slot

**Permissions:** ⚪ `booking_waitlist.manage`

Path parameters:
- `id` (string, required) — Waitlist entry ID

Response 200 — Default Response

```ts
{
  status: "success"
  data: {
    id: string // uuid
    locationId: number
    userId: number
    requestedDate: string // date
    preferredStartTime?: string | null
    preferredEndTime?: string | null
    partySize: number
    status: "waiting" | "notified" | "converted" | "expired" | "removed"
    convertedBookingId?: string | null // uuid
    expiresAt?: string | null // date-time
    notifiedAt?: string | null // date-time
    createdAt: string // date-time
    updatedAt: string // date-time
    userName?: string | null
    userEmail?: string | null
    userPhone?: string | null
  }
  meta: {
    requestId: string
    timestamp: string // date-time
    executionTimeMs: number
  }
}
```