Orders API: Create and Track Restaurant Orders Live

An order in La Previa Restobar is the primary unit of work: it links a table to a list of menu items and tracks the full journey from the moment a waiter submits it to the kitchen through to payment. Each order moves through a defined set of statuses; the status field drives UI state on both the waiter’s Android device and the kitchen display. When an order is confirmed (moves to ACEPTADO), the inventory subsystem decrements stock for every item that has trackInventory: true.

Order Status Lifecycle

PENDING → ENVIADO → ACEPTADO → EN_PREPARACION → LISTO → ENTREGADO → COMPLETED
                                                                    ↘ CANCELLED

Status	Meaning
`PENDING`	Order created locally, not yet sent to the backend
`ENVIADO`	Order sent to the server and visible to kitchen staff
`ACEPTADO`	Kitchen has acknowledged and accepted the order
`EN_PREPARACION`	Kitchen is actively preparing the dishes
`LISTO`	Food is ready for pick-up or delivery to the table
`ENTREGADO`	Food has been delivered to the table; table remains occupied
`COMPLETED`	Order settled; table can be cleared
`CANCELLED`	Order was cancelled before completion

OrderDto — API Response Fields

The fields below describe OrderDto, the object returned by every orders API endpoint. The Android OrderDto is intentionally lightweight — it carries exactly the fields listed here.

string

required

Unique order identifier (UUID or Firebase push key).

tableId

integer

required

Numeric ID of the table this order belongs to.

tableNumber

integer

required

Human-readable table number shown on receipts and kitchen tickets.

status

string

required

Current order status. One of PENDING, ENVIADO, ACEPTADO, EN_PREPARACION, LISTO, ENTREGADO, COMPLETED, CANCELLED.

total

number

required

Total order amount in local currency. Equal to the sum of all item.subtotal values.

createdAt

number

required

Unix epoch timestamp (milliseconds) when the order was created.

updatedAt

number

required

Unix epoch timestamp (milliseconds) of the last status change.

Local model fields: The fields waiterId, waiterName, notes, version, syncStatus, and items exist on the local Order model (used by Room and the Android ViewModel) but are not part of OrderDto and are therefore not returned by the API. The items array lives in the Firebase document and is populated when the Android client hydrates the record from its local Room cache. The version and syncStatus fields are managed client-side only.

Local Order model — additional fields (not in API response)

These fields are present on the Order data class used by the Android app after mapping from OrderDto:

waiterId

string | null

ID of the waiter who created the order. May be null for orders created without an authenticated session.

waiterName

string | null

Display name of the waiter, used on kitchen tickets.

notes

string | null

Free-text notes from the waiter (e.g. "sin cebolla", "alergia a mariscos").

version

number

Optimistic concurrency counter. Incremented on every write.

syncStatus

string

Local sync state on the Android client. Values: PENDING, SYNCED, ERROR. Defaults to PENDING.

items

array

List of ordered items. Each element is an OrderItem.

Show OrderItem fields

productId

string

ID of the product that was ordered.

productName

string

Name of the product at the time of ordering (denormalised snapshot).

productDescription

string

Description snapshot at the time of ordering.

productPrice

number

Listed sale price of the product at the time of ordering.

productCategory

string

Category snapshot at the time of ordering.

trackInventory

boolean

Whether this product’s stock should be decremented when the order is confirmed.

quantity

integer

Number of units ordered.

unitPrice

number

Actual unit price charged (may differ from productPrice if a discount was applied).

subtotal

number

quantity × unitPrice. Contributes to the order total.

GET /orders

Returns every order stored in Firebase, regardless of status or table.

curl -X GET http://localhost:3000/orders \
  -H "Accept: application/json"

Response 200 OK

[
  {
    "id": "order_11a2b3",
    "tableId": 3,
    "tableNumber": 3,
    "status": "EN_PREPARACION",
    "createdAt": 1717201000000,
    "updatedAt": 1717201500000,
    "total": 4500.0
  }
]

GET /orders/table/{tableId}

Returns all orders associated with a specific table, ordered by createdAt descending in the Firebase query. Path parameters

tableId

integer

required

The numeric table ID to filter by.

curl -X GET http://localhost:3000/orders/table/3 \
  -H "Accept: application/json"

Response 200 OK — same shape as GET /orders but scoped to the given table.

[
  {
    "id": "order_11a2b3",
    "tableId": 3,
    "tableNumber": 3,
    "status": "LISTO",
    "createdAt": 1717201000000,
    "updatedAt": 1717203000000,
    "total": 4500.0
  }
]

POST /orders

Creates a new order and writes it to the orders node in Firebase. The Android client typically calls this after the waiter finishes building the item list and taps “Enviar pedido”. Request body (CreateOrderDto)

tableId

integer

required

ID of the table for this order.

total

number

required

Pre-calculated total amount. Should equal the sum of item.unitPrice × item.quantity for all items.

items

array

required

List of items to include in the order.

Show OrderItemDto fields

productId

string

required

ID of the product being ordered.

quantity

integer

required

Number of units.

unitPrice

number

required

Price per unit at the time of ordering.

notes

string

Optional per-item note (e.g. "sin sal"). Defaults to null.

curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -d '{
    "tableId": 3,
    "total": 4500.0,
    "items": [
      {
        "productId": "prod_abc123",
        "quantity": 2,
        "unitPrice": 1500.0,
        "notes": null
      },
      {
        "productId": "prod_xyz789",
        "quantity": 2,
        "unitPrice": 750.0,
        "notes": "sin cebolla"
      }
    ]
  }'

Response 200 OK — returns the newly created OrderDto.

{
  "id": "order_44d5e6",
  "tableId": 3,
  "tableNumber": 3,
  "status": "ENVIADO",
  "createdAt": 1717205000000,
  "updatedAt": 1717205000000,
  "total": 4500.0
}

PUT /orders/{id}/status

Advances or changes an order’s status. This is the primary way the kitchen display, waiter app, and cashier all coordinate on a single order. Path parameters

string

required

The order’s unique identifier.

Request body (OrderStatusUpdateRequest)

status

string

required

The new status value. Must be one of: PENDING, ENVIADO, ACEPTADO, EN_PREPARACION, LISTO, ENTREGADO, COMPLETED, CANCELLED.

curl -X PUT http://localhost:3000/orders/order_44d5e6/status \
  -H "Content-Type: application/json" \
  -d '{"status": "ACEPTADO"}'

Response 200 OK — returns the OrderDto with the updated status and a refreshed updatedAt timestamp.

{
  "id": "order_44d5e6",
  "tableId": 3,
  "tableNumber": 3,
  "status": "ACEPTADO",
  "createdAt": 1717205000000,
  "updatedAt": 1717205800000,
  "total": 4500.0
}

REST API

Infrastructure

Orders API: Create and Track Restaurant Orders Live

Order Status Lifecycle

OrderDto — API Response Fields

Local Order model — additional fields (not in API response)

GET /orders

GET /orders/table/{tableId}

POST /orders

PUT /orders/{id}/status

Build docs developers (and LLMs) love

REST API

Infrastructure

Documentation Index

​Order Status Lifecycle

​OrderDto — API Response Fields

​Local Order model — additional fields (not in API response)

​GET /orders

​GET /orders/table/{tableId}

​POST /orders

​PUT /orders/{id}/status

Build docs developers (and LLMs) love

Order Status Lifecycle

OrderDto — API Response Fields

Local Order model — additional fields (not in API response)

GET /orders

GET /orders/table/{tableId}

POST /orders

PUT /orders/{id}/status