curl -X POST https://api.restai.com/api/orders \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "type": "dine_in", "customerName": "John Doe", "notes": "Extra napkins please", "items": [ { "menuItemId": "123e4567-e89b-12d3-a456-426614174000", "quantity": 2, "notes": "No onions", "modifiers": [ { "modifierId": "987fcdeb-51a2-43f7-9c8d-123456789abc" } ] }, { "menuItemId": "456e7890-e89b-12d3-a456-426614174001", "quantity": 1 } ], "couponCode": "SUMMER20", "redemptionId": "789fedcb-a123-45f6-9d8e-456789abcdef" }'
POST /api/orders Creates a new order with one or more menu items. The order is automatically assigned an order number and calculates totals including tax and any applicable discounts.
Authentication Requires orders:create permission (waiter, cashier, branch_manager, org_admin).
Request Body Order type. Options: dine_in, takeout, delivery
Customer’s name (optional for dine-in, recommended for takeout/delivery)
Special instructions or notes for the order (max 500 characters)
Array of order items (minimum 1 item required) Special instructions for this item (max 500 characters)
Array of modifier objects UUID of the modifier to add
Optional coupon code to apply discount (max 50 characters)
UUID of a loyalty reward redemption to apply
Response Indicates if the request was successful
The created order object Table session UUID (null for non-table orders)
Customer UUID (null for guest orders)
Human-readable order number (e.g., “ORD-001”)
Order type: dine_in, takeout, or delivery
Current order status: pending, confirmed, preparing, ready, served, completed, or cancelled
Subtotal in cents (before tax and discounts)
Total amount in cents (subtotal + tax - discount)
Whether inventory has been deducted for this order
ISO 8601 timestamp of when the order was created
ISO 8601 timestamp of last update
Array of order items Item name (snapshot at time of order)
Item total in cents (unit_price × quantity)
Item status: pending, preparing, ready, served, or cancelled
Error Responses false when an error occurs
Error details Error code: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND
Human-readable error message
Example Response { "success" : true , "data" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "organization_id" : "123e4567-e89b-12d3-a456-426614174000" , "branch_id" : "789e4567-e89b-12d3-a456-426614174111" , "table_session_id" : null , "customer_id" : null , "order_number" : "ORD-00042" , "type" : "dine_in" , "status" : "pending" , "customer_name" : "John Doe" , "subtotal" : 3200 , "tax" : 576 , "discount" : 0 , "total" : 3776 , "notes" : "Extra napkins please" , "inventory_deducted" : false , "created_at" : "2024-01-15T14:30:00.000Z" , "updated_at" : "2024-01-15T14:30:00.000Z" , "items" : [ { "id" : "660e8400-e29b-41d4-a716-446655440001" , "order_id" : "550e8400-e29b-41d4-a716-446655440000" , "menu_item_id" : "123e4567-e89b-12d3-a456-426614174000" , "name" : "Cheeseburger" , "unit_price" : 1200 , "quantity" : 2 , "total" : 2400 , "notes" : "No onions" , "status" : "pending" }, { "id" : "770e8400-e29b-41d4-a716-446655440002" , "order_id" : "550e8400-e29b-41d4-a716-446655440000" , "menu_item_id" : "456e7890-e89b-12d3-a456-426614174001" , "name" : "French Fries" , "unit_price" : 800 , "quantity" : 1 , "total" : 800 , "notes" : null , "status" : "pending" } ] } }
WebSocket Notification When an order is created, a WebSocket event is broadcast to:
branch:{branchId} - Notifies all branch staffbranch:{branchId}:kitchen - Updates kitchen display
{ "type" : "order:new" , "payload" : { "orderId" : "550e8400-e29b-41d4-a716-446655440000" , "orderNumber" : "ORD-00042" , "status" : "pending" , "items" : [ { "id" : "660e8400-e29b-41d4-a716-446655440001" , "name" : "Cheeseburger" , "quantity" : 2 , "status" : "pending" , "notes" : "No onions" }, { "id" : "770e8400-e29b-41d4-a716-446655440002" , "name" : "French Fries" , "quantity" : 1 , "status" : "pending" , "notes" : null } ] }, "timestamp" : 1705330200000 }
Notes
All monetary values are in cents (e.g., $32.00 = 3200)
Order numbers are automatically generated and sequential per branch
Tax rate is configured per branch (default 18% for Peru)
For customer roles, table_session_id is automatically determined from active session
Orders with loyalty redemptions or coupons will have discounts applied automatically
Menu items must exist and be available at the branch. The system validates inventory and availability before creating the order.