Authenticated API

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

Kiosk API

Manage self-service kiosk devices, ordering sessions, and configuration.

Authentication Required

All endpoints require a Device Token or Bearer Token. Device tokens are issued during kiosk registration. See Authentication for details.

Overview

Attribute	Value
Base Path	/api/v1/kiosk
Authentication	Device Token or Bearer Token
Required Roles	pos_staff, server, restaurant_staff, restaurant_manager, kitchen, tenant_admin, platform_admin, system_admin, super_admin

Device Management

Register Kiosk

Register a new kiosk device.

POST /api/v1/kiosk/devices

Request Body

{
  "location_id": "loc_123",
  "name": "Kiosk 1",
  "hardware_id": "device_serial_123",
  "model": "olympus_k1",
  "position": "entrance_right"
}

Response

{
  "device_id": "kiosk_001",
  "device_token": "kt_abc123...",
  "location_id": "loc_123",
  "name": "Kiosk 1",
  "status": "online",
  "registered_at": "2026-01-24T10:00:00Z"
}

---

List Kiosks

Get all kiosks for a location.

GET /api/v1/kiosk/devices

Query Parameters

Parameter	Type	Description
location_id	uuid	Filter by location
status	string	online, offline, maintenance

Response

{
  "data": [
    {
      "device_id": "kiosk_001",
      "name": "Kiosk 1",
      "location_id": "loc_123",
      "status": "online",
      "current_session": null,
      "orders_today": 45,
      "last_heartbeat": "2026-01-24T18:29:00Z",
      "software_version": "3.2.1"
    }
  ]
}

---

Get Kiosk Status

Get detailed kiosk status.

GET /api/v1/kiosk/devices/{device_id}/status

Response

{
  "device_id": "kiosk_001",
  "status": "online",
  "mode": "ordering",
  "current_session": {
    "id": "sess_abc",
    "started_at": "2026-01-24T18:25:00Z",
    "cart_items": 3
  },
  "hardware": {
    "printer_status": "ready",
    "card_reader_status": "ready",
    "screen_brightness": 80
  },
  "metrics": {
    "orders_today": 45,
    "revenue_today": 678.50,
    "avg_order_value": 15.08,
    "conversion_rate": 0.72
  }
}

---

Heartbeat

Send device heartbeat (every 60 seconds).

POST /api/v1/kiosk/devices/{device_id}/heartbeat

Request Body

{
  "software_version": "3.2.1",
  "uptime_seconds": 43200,
  "memory_usage_percent": 45,
  "hardware_status": {
    "printer": "ready",
    "card_reader": "ready",
    "touchscreen": "ready"
  }
}

---

Session Management

Session Timeouts

Kiosk sessions automatically expire after the configured idle timeout (default: 180 seconds). A warning is displayed 60 seconds before timeout. Expired sessions cannot be resumed -- a new session must be started.

Start Session

Begin a new ordering session.

POST /api/v1/kiosk/sessions

Request Body

{
  "device_id": "kiosk_001",
  "language": "en",
  "accessibility_mode": false
}

Response

{
  "session_id": "sess_abc",
  "device_id": "kiosk_001",
  "started_at": "2026-01-24T18:25:00Z",
  "timeout_seconds": 180,
  "menu_version": "2026-01-24-1"
}

---

Get Session

Retrieve current session state.

GET /api/v1/kiosk/sessions/{session_id}

Response

{
  "session_id": "sess_abc",
  "status": "active",
  "cart": {
    "items": [
      {
        "id": "cart_001",
        "menu_item_id": "item_123",
        "name": "Burger Combo",
        "quantity": 1,
        "modifiers": [
          {"id": "mod_001", "name": "No Onions"}
        ],
        "unit_price": 12.99,
        "total": 12.99
      }
    ],
    "subtotal": 12.99,
    "tax": 1.17,
    "total": 14.16
  },
  "idle_seconds": 15,
  "timeout_warning": false
}

---

Add to Cart

Add item to session cart.

POST /api/v1/kiosk/sessions/{session_id}/cart

Request Body

{
  "menu_item_id": "item_123",
  "quantity": 1,
  "modifiers": [
    {"modifier_id": "mod_001", "quantity": 1}
  ],
  "special_instructions": "Extra napkins please"
}

---

Update Cart Item

Modify cart item quantity or modifiers.

PUT /api/v1/kiosk/sessions/{session_id}/cart/{cart_item_id}

---

Remove from Cart

Remove item from cart.

DELETE /api/v1/kiosk/sessions/{session_id}/cart/{cart_item_id}

---

Complete Order

Submit the order.

POST /api/v1/kiosk/sessions/{session_id}/checkout

Request Body

{
  "payment_method": "card",
  "order_type": "dine_in",
  "customer_name": "John"
}

Response

{
  "order_id": "ord_xyz",
  "order_number": "K-042",
  "status": "pending_payment",
  "total": 14.16,
  "payment_terminal_request": {
    "amount": 14.16,
    "transaction_id": "txn_abc"
  }
}

---

End Session

Terminate session (timeout or cancel).

DELETE /api/v1/kiosk/sessions/{session_id}

Query Parameters

Parameter	Type	Description
reason	string	timeout, cancelled, completed

---

Configuration

Get Kiosk Configuration

Retrieve kiosk display and behavior settings.

GET /api/v1/kiosk/devices/{device_id}/config

Response

{
  "display": {
    "language": "en",
    "theme": "light",
    "font_size": "medium",
    "attract_mode_enabled": true,
    "attract_mode_timeout_seconds": 30
  },
  "ordering": {
    "allow_dine_in": true,
    "allow_takeout": true,
    "require_name": true,
    "suggest_upsells": true,
    "max_items_per_order": 20
  },
  "payment": {
    "accepted_methods": ["card", "apple_pay", "google_pay"],
    "allow_cash": false,
    "tip_enabled": true,
    "tip_presets": [15, 18, 20]
  },
  "accessibility": {
    "high_contrast_available": true,
    "large_text_available": true,
    "audio_assistance": true,
    "wheelchair_height": true
  },
  "timeout": {
    "idle_warning_seconds": 120,
    "idle_timeout_seconds": 180,
    "payment_timeout_seconds": 120
  }
}

---

Update Configuration

Update kiosk settings.

PUT /api/v1/kiosk/devices/{device_id}/config

---

Attract Mode

Set Attract Content

Configure attract mode display.

PUT /api/v1/kiosk/devices/{device_id}/attract

Request Body

{
  "slides": [
    {
      "type": "image",
      "url": "https://...",
      "duration_seconds": 5
    },
    {
      "type": "video",
      "url": "https://...",
      "duration_seconds": 15
    },
    {
      "type": "promotion",
      "promotion_id": "promo_001",
      "duration_seconds": 8
    }
  ],
  "call_to_action": "Touch to Start Ordering"
}

---

Analytics

Get Kiosk Analytics

Retrieve kiosk performance metrics.

GET /api/v1/kiosk/analytics

Query Parameters

Parameter	Type	Description
location_id	uuid	Filter by location
device_id	string	Specific kiosk
start_date	date	Analysis start
end_date	date	Analysis end

Response

{
  "period": {
    "start": "2026-01-24",
    "end": "2026-01-24"
  },
  "summary": {
    "total_sessions": 180,
    "completed_orders": 130,
    "conversion_rate": 0.72,
    "abandoned_sessions": 50,
    "total_revenue": 1950.00,
    "avg_order_value": 15.00
  },
  "by_device": [
    {
      "device_id": "kiosk_001",
      "sessions": 95,
      "orders": 70,
      "revenue": 1050.00
    }
  ],
  "popular_items": [
    {"item_id": "item_123", "name": "Burger Combo", "count": 45}
  ],
  "peak_hours": [12, 13, 18, 19]
}

---

Webhooks

Event	Description
kiosk.online	Kiosk came online
kiosk.offline	Kiosk went offline
kiosk.session_started	New session began
kiosk.order_completed	Order submitted
kiosk.session_abandoned	Session timed out
kiosk.hardware_alert	Hardware issue detected

---

Error Responses

Status	Code	Description
400	session_timeout	Session has expired
400	cart_empty	Cannot checkout empty cart
404	device_not_found	Kiosk not registered
409	device_busy	Another session active
503	device_offline	Kiosk is offline

---

Related Documentation

• Kiosk User Guide - Kiosk setup guide
• Kiosk Ordering - Customer experience
• Orders API - Order management