Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/commerce/*.

Reservations & Waitlist API

Manage restaurant reservations, check availability, and handle waitlist operations.

Authentication Required

All endpoints require a valid Bearer token. See Authentication for details.

Overview

Attribute	Value
Base Path	`/api/v1/reservations`, `/api/v1/waitlist`
Authentication	Bearer Token
Required Roles	`pos_staff`, `restaurant_staff`, `server`, `host`, `manager`, `restaurant_manager`, `tenant_admin`, `platform_admin`, `system_admin`, `super_admin`

Reservation Endpoints

Create Reservation

Create a new reservation.

POST /api/v1/reservations

Request Body

{
  "location_id": "loc_abc123",
  "customer_name": "John Smith",
  "customer_email": "john@example.com",
  "customer_phone": "+1234567890",
  "party_size": 4,
  "reservation_date": "2026-01-25",
  "reservation_time": "19:00",
  "duration_minutes": 90,
  "special_requests": "Anniversary dinner, quiet table",
  "tags": ["anniversary", "vip"]
}

Response 201 Created

{
  "id": "res_xyz789",
  "confirmation_code": "RR-4521",
  "location_id": "loc_abc123",
  "customer_name": "John Smith",
  "customer_email": "john@example.com",
  "party_size": 4,
  "reservation_datetime": "2026-01-25T19:00:00Z",
  "duration_minutes": 90,
  "status": "confirmed",
  "table_preferences": [],
  "special_requests": "Anniversary dinner, quiet table",
  "created_at": "2026-01-24T10:00:00Z"
}

List Reservations

Retrieve reservations with filtering options.

GET /api/v1/reservations

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Filter by location
`date`	date	Filter by date (YYYY-MM-DD)
`status`	string	`pending`, `confirmed`, `seated`, `completed`, `cancelled`, `no_show`
`customer_email`	string	Filter by customer email
`page`	integer	Page number
`limit`	integer	Results per page

Response

{
  "data": [
    {
      "id": "res_xyz789",
      "confirmation_code": "RR-4521",
      "customer_name": "John Smith",
      "party_size": 4,
      "reservation_datetime": "2026-01-25T19:00:00Z",
      "status": "confirmed",
      "table_id": null,
      "created_at": "2026-01-24T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}

Get Reservation

Retrieve a single reservation by ID.

GET /api/v1/reservations/{id}

Update Reservation

Modify reservation details.

PUT /api/v1/reservations/{id}

Request Body

{
  "party_size": 6,
  "reservation_time": "19:30",
  "special_requests": "Need high chair"
}

Update Reservation Status

Change reservation status.

PATCH /api/v1/reservations/{id}/status

Request Body

{
  "status": "confirmed"
}

Status Values

Status	Description
`pending`	Awaiting confirmation
`confirmed`	Confirmed by restaurant
`seated`	Guest has been seated
`completed`	Visit completed
`cancelled`	Cancelled by guest or restaurant
`no_show`	Guest did not arrive

Cancel Reservation

Cancel a reservation.

POST /api/v1/reservations/{id}/cancel

Request Body

{
  "reason": "Customer requested cancellation"
}

Confirm Reservation

Confirm a pending reservation.

POST /api/v1/reservations/{id}/confirm

Seat Reservation

Mark guest as seated and assign table.

POST /api/v1/reservations/{id}/seat

Request Body

{
  "table_id": "tbl_002"
}

Mark No-Show

Mark a reservation as no-show.

POST /api/v1/reservations/{id}/noshow

Check Availability

Check available time slots for a date.

GET /api/v1/reservations/availability

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`date`	date	Date to check
`party_size`	integer	Number of guests
`duration_minutes`	integer	Desired duration (optional)

Response

{
  "date": "2026-01-25",
  "location_id": "loc_abc123",
  "party_size": 4,
  "available_slots": [
    {
      "time": "17:00",
      "available_tables": 3,
      "wait_time_minutes": 0
    },
    {
      "time": "17:30",
      "available_tables": 2,
      "wait_time_minutes": 0
    },
    {
      "time": "18:00",
      "available_tables": 0,
      "wait_time_minutes": 15
    },
    {
      "time": "19:00",
      "available_tables": 1,
      "wait_time_minutes": 0
    }
  ]
}

Waitlist Endpoints

Add to Waitlist

Add a party to the waitlist.

POST /api/v1/waitlist

Request Body

{
  "location_id": "loc_abc123",
  "customer_name": "Jane Doe",
  "customer_phone": "+1234567890",
  "party_size": 2,
  "quoted_wait_minutes": 20,
  "notes": "Prefers booth"
}

Response 201 Created

{
  "id": "wl_abc123",
  "position": 3,
  "customer_name": "Jane Doe",
  "party_size": 2,
  "quoted_wait_minutes": 20,
  "actual_wait_minutes": null,
  "status": "waiting",
  "check_in_time": "2026-01-24T18:30:00Z"
}

Get Waitlist

View current waitlist for a location.

GET /api/v1/waitlist

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`status`	string	`waiting`, `notified`, `seated`, `cancelled`, `expired`

Response

{
  "data": [
    {
      "id": "wl_abc123",
      "position": 1,
      "customer_name": "Jane Doe",
      "party_size": 2,
      "quoted_wait_minutes": 20,
      "elapsed_wait_minutes": 12,
      "status": "waiting"
    }
  ],
  "summary": {
    "total_waiting": 5,
    "average_wait_minutes": 18,
    "longest_wait_minutes": 35
  }
}

Get Wait Time Estimate

Get estimated wait time for a party size.

GET /api/v1/waitlist/estimate

Query Parameters

Parameter	Type	Description
`location_id`	uuid	Restaurant location
`party_size`	integer	Number of guests

Response

{
  "location_id": "loc_abc123",
  "party_size": 4,
  "estimated_wait_minutes": 25,
  "confidence": "high",
  "current_waitlist_size": 5,
  "tables_available_soon": 2
}

Get Waitlist Entry

Retrieve a specific waitlist entry.

GET /api/v1/waitlist/{id}

Update Waitlist Status

Change waitlist entry status.

PATCH /api/v1/waitlist/{id}/status

Request Body

{
  "status": "notified",
  "table_id": "tbl_005"
}

Notify Waitlist Party

Send notification that table is ready.

POST /api/v1/waitlist/{id}/notify

Sends SMS/push notification to customer.

Seat Waitlist Party

Seat a waitlist party at a table.

POST /api/v1/waitlist/{id}/seat

Request Body

{
  "table_id": "tbl_005"
}

Cancel Waitlist Entry

Remove party from waitlist.

POST /api/v1/waitlist/{id}/cancel

Request Body

{
  "reason": "Customer left"
}

Webhooks

Event	Description
`reservation.created`	New reservation created
`reservation.confirmed`	Reservation confirmed
`reservation.cancelled`	Reservation cancelled
`reservation.seated`	Guest seated
`reservation.no_show`	Marked as no-show
`waitlist.added`	Party added to waitlist
`waitlist.notified`	Party notified table ready
`waitlist.seated`	Waitlist party seated

Error Responses

Status	Code	Description
400	`invalid_date`	Date format invalid
400	`invalid_party_size`	Party size must be 1-20
400	`past_datetime`	Cannot book in the past
404	`reservation_not_found`	Reservation ID not found
409	`no_availability`	No tables available for time
409	`already_seated`	Reservation already seated

Tables API - Table management
Seating API - Seating management
Waitlist Guide - Waitlist management

Overview​

Reservation Endpoints​

Create Reservation​

List Reservations​

Get Reservation​

Update Reservation​

Update Reservation Status​

Status Values​

Cancel Reservation​

Confirm Reservation​

Seat Reservation​

Mark No-Show​

Check Availability​

Waitlist Endpoints​

Add to Waitlist​

Get Waitlist​

Get Wait Time Estimate​

Get Waitlist Entry​

Update Waitlist Status​

Notify Waitlist Party​

Seat Waitlist Party​

Cancel Waitlist Entry​

Webhooks​

Error Responses​

Related Documentation​

Overview

Reservation Endpoints

Create Reservation

List Reservations

Get Reservation

Update Reservation

Update Reservation Status

Status Values

Cancel Reservation

Confirm Reservation

Seat Reservation

Mark No-Show

Check Availability

Waitlist Endpoints

Add to Waitlist

Get Waitlist

Get Wait Time Estimate

Get Waitlist Entry

Update Waitlist Status

Notify Waitlist Party

Seat Waitlist Party

Cancel Waitlist Entry

Webhooks

Error Responses

Related Documentation