Skip to main content
curl -X PATCH https://api.restai.com/api/orders/550e8400-e29b-41d4-a716-446655440000/status \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "preparing"
  }'

​
PATCH /api/orders/:id/status

Updates an order’s status. Status transitions must follow the defined workflow.

​
Authentication

Requires orders:update permission (waiter, cashier, branch_manager, org_admin).

​
Path Parameters

​
id
string
required
UUID of the order to update

​
Request Body

​
status
string
required
New status for the order. Must be a valid transition from the current status.Options: pending, confirmed, preparing, ready, served, completed, cancelled

​
Allowed Status Transitions

Orders can only transition to specific statuses based on their current state:
Current StatusAllowed Next Statuses
pendingconfirmed, preparing, cancelled
confirmedpreparing, cancelled
preparingready, cancelled
readyserved
servedcompleted
completed(terminal state)
cancelled(terminal state)
Attempting an invalid transition will return a 400 error.

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
The updated order object

​
Error Responses

​
success
boolean
false when an error occurs
​
error
object
Error details

​
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": "preparing",
    "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:35:00.000Z"
  }
}

​
Error Example - Invalid Transition

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "No se puede cambiar de \"completed\" a \"preparing\""
  }
}

​
Completed Status Side Effects

When an order is transitioned to completed status, the following side effects occur:
1

Loyalty Points

If the order has an associated customer, loyalty points are awarded based on the order total
2

Inventory Deduction

If inventory management is enabled and inventory_deducted is false, ingredient stock is automatically deducted
Once an order is marked as completed or cancelled, it cannot be changed to any other status.

​
WebSocket Notification

When order status is updated, WebSocket events are broadcast to:
  • branch:{branchId} - All branch staff
  • branch:{branchId}:kitchen - Kitchen displays
  • session:{sessionId} - Customer apps (if order has a table session)
{
  "type": "order:updated",
  "payload": {
    "orderId": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-00042",
    "status": "preparing"
  },
  "timestamp": 1705330500000
}

Kitchen Management

Update individual order item status (used by kitchen staff)

​
Notes

  • Status transitions are validated server-side based on ORDER_STATUS_TRANSITIONS
  • Updating to completed triggers loyalty points calculation and inventory deduction
  • Kitchen staff typically use item-level status updates rather than full order status changes
  • The updated_at timestamp is automatically set to the current time

Build docs developers (and LLMs) love

Get started for freeTalk to us