Skip to main content
Authenticated API

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

Tables API

Manage restaurant tables, seating assignments, and track table turnover.

Authentication Required

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

Overview​

AttributeValue
Base Path/api/v1/tables
AuthenticationBearer Token
Required Rolespos_staff, restaurant_staff, server, bartender, cashier, chef, kitchen, host, manager, restaurant_manager, tenant_admin, platform_admin, system_admin, super_admin

Endpoints​

List Tables​

Retrieve all tables for a location with status information.

GET /api/v1/tables/{location_id}

Path Parameters

ParameterTypeDescription
location_iduuidRestaurant location ID

Response

{
  "data": [
    {
      "id": "tbl_001",
      "number": "1",
      "name": "Table 1",
      "section": "Main Dining",
      "capacity": 4,
      "status": "available",
      "shape": "round",
      "position": {"x": 100, "y": 150},
      "current_order_id": null,
      "server_id": "staff_abc",
      "server_name": "Jane Smith"
    },
    {
      "id": "tbl_002",
      "number": "2",
      "name": "Booth 2",
      "section": "Main Dining",
      "capacity": 6,
      "status": "occupied",
      "shape": "rectangle",
      "position": {"x": 200, "y": 150},
      "current_order_id": "ord_xyz789",
      "seated_at": "2026-01-24T18:30:00Z",
      "party_size": 4,
      "server_id": "staff_abc",
      "server_name": "Jane Smith"
    }
  ]
}

Table Status Values​

StatusDescription
availableTable is clean and ready
occupiedGuests are seated
reservedReserved for upcoming party
dirtyNeeds bussing/cleaning
blockedTemporarily unavailable

Get Table​

Retrieve details for a specific table.

GET /api/v1/tables/{table_id}

Response

{
  "id": "tbl_002",
  "number": "2",
  "name": "Booth 2",
  "section": "Main Dining",
  "section_id": "sec_main",
  "capacity": 6,
  "min_capacity": 2,
  "status": "occupied",
  "shape": "rectangle",
  "dimensions": {"width": 48, "height": 72},
  "position": {"x": 200, "y": 150, "rotation": 0},
  "current_order": {
    "id": "ord_xyz789",
    "order_number": "A-0042",
    "party_size": 4,
    "seated_at": "2026-01-24T18:30:00Z",
    "subtotal": 85.50,
    "items_count": 6
  },
  "server": {
    "id": "staff_abc",
    "name": "Jane Smith"
  },
  "features": ["window", "power_outlet"],
  "created_at": "2025-06-01T00:00:00Z"
}

Assign Table to Order​

Assign a table to an existing order.

PUT /api/v1/tables/{table_id}/assign

Request Body

{
  "order_id": "ord_xyz789",
  "party_size": 4
}

Response

{
  "table": {
    "id": "tbl_002",
    "status": "occupied",
    "seated_at": "2026-01-24T18:30:00Z"
  },
  "order": {
    "id": "ord_xyz789",
    "table_id": "tbl_002",
    "table_number": "2"
  }
}

Events Published

  • table.assigned - Table assigned to order
  • order.table_assigned - Order received table assignment

Update Table Status​

Change a table's status.

PATCH /api/v1/tables/{table_id}/status

Request Body

{
  "status": "dirty"
}

Response

{
  "id": "tbl_002",
  "status": "dirty",
  "status_changed_at": "2026-01-24T20:15:00Z",
  "status_changed_by": "staff_abc"
}

Clear Table​

Mark a table as cleared and ready for cleaning.

POST /api/v1/tables/{table_id}/clear

This action:

  1. Sets table status to dirty
  2. Clears current order association
  3. Records turnover timestamp

Response 204 No Content

Get Table Assignments​

List all current table assignments for a location.

GET /api/v1/tables/{location_id}/assignments

Response

{
  "data": [
    {
      "table_id": "tbl_002",
      "table_number": "2",
      "order_id": "ord_xyz789",
      "party_size": 4,
      "seated_at": "2026-01-24T18:30:00Z",
      "server_id": "staff_abc",
      "duration_minutes": 45
    }
  ],
  "summary": {
    "occupied_tables": 12,
    "available_tables": 8,
    "total_seated_guests": 42
  }
}

Get Turnover Metrics​

Retrieve table turnover analytics.

GET /api/v1/tables/{location_id}/turnover

Query Parameters

ParameterTypeDescription
start_datedatetimeStart of period (ISO 8601)
end_datedatetimeEnd of period (ISO 8601)

Response

{
  "period": {
    "start": "2026-01-24T00:00:00Z",
    "end": "2026-01-24T23:59:59Z"
  },
  "metrics": {
    "total_turns": 45,
    "avg_turn_time_minutes": 52,
    "avg_party_size": 3.2,
    "peak_occupancy_percent": 95,
    "revenue_per_seat_hour": 18.50
  },
  "by_section": [
    {
      "section": "Main Dining",
      "turns": 30,
      "avg_turn_time_minutes": 48
    },
    {
      "section": "Patio",
      "turns": 15,
      "avg_turn_time_minutes": 62
    }
  ],
  "by_hour": [
    {"hour": 17, "turns": 8, "occupancy_percent": 60},
    {"hour": 18, "turns": 12, "occupancy_percent": 85},
    {"hour": 19, "turns": 15, "occupancy_percent": 95}
  ]
}

Floor Plan Management​

Get Floor Plan​

Retrieve the floor plan layout.

GET /api/v1/locations/{location_id}/floor-plan

Response

{
  "location_id": "loc_abc123",
  "dimensions": {"width": 800, "height": 600},
  "sections": [
    {
      "id": "sec_main",
      "name": "Main Dining",
      "color": "#4A90D9",
      "bounds": {"x": 0, "y": 0, "width": 500, "height": 600}
    },
    {
      "id": "sec_patio",
      "name": "Patio",
      "color": "#7BC96F",
      "bounds": {"x": 500, "y": 0, "width": 300, "height": 600}
    }
  ],
  "tables": [...],
  "fixtures": [
    {"type": "bar", "position": {"x": 50, "y": 50}},
    {"type": "host_stand", "position": {"x": 400, "y": 50}}
  ]
}

Webhooks​

Subscribe to table events via webhooks:

EventDescription
table.status_changedTable status updated
table.assignedTable assigned to order
table.clearedTable cleared after guests left
table.reservedTable reserved for party

Error Responses​

StatusCodeDescription
400missing_location_idLocation ID is required
400invalid_statusStatus value not recognized
404table_not_foundTable ID does not exist
409table_occupiedTable already has active order