POS API

The POS API provides access to restaurant and outlet operations including orders, billing, and menu management.

Endpoints

Orders

List Orders

GET /api/v1/pos/orders

Query Parameters:

Parameter	Type	Description
outlet_id	string	Filter by outlet
status	string	Filter by status (OPEN, CLOSED, etc.)
table_number	string	Filter by table
date	date	Filter by date
cursor	string	Pagination cursor

Response:

{
  "data": [
    {
      "id": "order_123",
      "order_number": "ORD20260122001",
      "outlet": {
        "id": "outlet_rest01",
        "name": "Main Restaurant"
      },
      "table_number": "T05",
      "status": "OPEN",
      "covers": 4,
      "items": [
        {
          "id": "item_1",
          "menu_item_id": "menu_pasta",
          "name": "Pasta Carbonara",
          "quantity": 2,
          "unit_price": 450.00,
          "total": 900.00,
          "modifiers": ["Extra cheese"],
          "status": "SERVED"
        }
      ],
      "subtotal": 2500.00,
      "tax": 450.00,
      "service_charge": 250.00,
      "total": 3200.00,
      "created_at": "2026-01-22T19:30:00Z"
    }
  ]
}

Create Order

POST /api/v1/pos/orders

Request Body:

{
  "outlet_id": "outlet_rest01",
  "table_number": "T05",
  "covers": 4,
  "items": [
    {
      "menu_item_id": "menu_pasta",
      "quantity": 2,
      "modifiers": ["Extra cheese"],
      "notes": "Al dente"
    },
    {
      "menu_item_id": "menu_wine",
      "quantity": 1
    }
  ],
  "guest_id": "guest_abc123",
  "room_number": "405"
}

Add Items to Order

POST /api/v1/pos/orders/:id/items

Request Body:

{
  "items": [
    {
      "menu_item_id": "menu_dessert",
      "quantity": 2
    }
  ]
}

Update Item Status

PUT /api/v1/pos/orders/:orderId/items/:itemId

Request Body:

{
  "status": "SERVED"
}

Billing

Get Bill

GET /api/v1/pos/orders/:id/bill

Response:

{
  "data": {
    "order_id": "order_123",
    "bill_number": "BILL20260122001",
    "outlet": "Main Restaurant",
    "table": "T05",
    "items": [
      {
        "name": "Pasta Carbonara x2",
        "amount": 900.00
      },
      {
        "name": "House Wine x1",
        "amount": 800.00
      },
      {
        "name": "Chocolate Cake x2",
        "amount": 500.00
      }
    ],
    "subtotal": 2200.00,
    "cgst": 198.00,
    "sgst": 198.00,
    "service_charge": 220.00,
    "total": 2816.00,
    "generated_at": "2026-01-22T21:00:00Z"
  }
}

Settle Bill

POST /api/v1/pos/orders/:id/settle

Request Body:

{
  "payments": [
    {
      "method": "CREDIT_CARD",
      "amount": 2816.00,
      "reference": "TXN123456"
    }
  ]
}

Transfer to Room

POST /api/v1/pos/orders/:id/transfer-to-room

Request Body:

{
  "room_number": "405",
  "guest_signature": true
}

Split Bill

POST /api/v1/pos/orders/:id/split

Request Body:

{
  "split_type": "BY_ITEM",
  "splits": [
    {
      "items": ["item_1", "item_2"],
      "payment": {
        "method": "CASH",
        "amount": 1500.00
      }
    },
    {
      "items": ["item_3"],
      "payment": {
        "method": "ROOM_CHARGE",
        "room_number": "405"
      }
    }
  ]
}

Menu Management

List Menu Items

GET /api/v1/pos/menu-items

Query Parameters:

Parameter	Type	Description
outlet_id	string	Filter by outlet
category_id	string	Filter by category
is_available	boolean	Filter by availability

Response:

{
  "data": [
    {
      "id": "menu_pasta",
      "code": "PASTA01",
      "name": "Pasta Carbonara",
      "description": "Creamy pasta with bacon and parmesan",
      "category": {
        "id": "cat_main",
        "name": "Main Course"
      },
      "price": 450.00,
      "tax_rate": 18,
      "is_available": true,
      "modifiers": [
        {
          "id": "mod_cheese",
          "name": "Extra cheese",
          "price": 50.00
        }
      ],
      "allergens": ["GLUTEN", "DAIRY"],
      "dietary": ["CONTAINS_PORK"]
    }
  ]
}

Update Item Availability

PUT /api/v1/pos/menu-items/:id/availability

Request Body:

{
  "is_available": false,
  "reason": "Out of stock"
}

Table Management

List Tables

GET /api/v1/pos/tables

Response:

{
  "data": [
    {
      "id": "table_01",
      "number": "T01",
      "outlet_id": "outlet_rest01",
      "capacity": 4,
      "status": "AVAILABLE",
      "section": "Indoor"
    },
    {
      "id": "table_05",
      "number": "T05",
      "outlet_id": "outlet_rest01",
      "capacity": 6,
      "status": "OCCUPIED",
      "section": "Indoor",
      "current_order": {
        "id": "order_123",
        "covers": 4,
        "opened_at": "2026-01-22T19:30:00Z"
      }
    }
  ]
}

Update Table Status

PUT /api/v1/pos/tables/:id/status

Request Body:

{
  "status": "RESERVED",
  "reservation_name": "Smith",
  "reservation_time": "2026-01-22T20:00:00Z"
}

Kitchen Display

Get Kitchen Orders

GET /api/v1/pos/kitchen/orders

Query Parameters:

Parameter	Type	Description
outlet_id	string	Filter by outlet
status	string	NEW, IN_PROGRESS, READY

Update Kitchen Item Status

PUT /api/v1/pos/kitchen/items/:id

Request Body:

{
  "status": "READY",
  "prepared_by": "chef_001"
}

Order Status Values

Status	Description
OPEN	Order is active
PRINTED	Bill printed
SETTLED	Payment received
CLOSED	Order completed
VOID	Order cancelled

Payment Methods

Method	Description
CASH	Cash payment
CREDIT_CARD	Credit/Debit card
ROOM_CHARGE	Charge to guest room
COMPANY	Company billing
VOUCHER	Gift voucher
LOYALTY	Loyalty points

Related Documentation

• POS Module
• Rooms API