Orders API — Create, Update, and Track Restaurant Orders

The Orders API manages the full lifecycle of a restaurant order — from the moment a waiter opens a ticket at a table to delivery and payment. It also powers the dashboard’s sales statistics panel. All endpoints require a valid JWT in the Authorization: Bearer <token> header. Role restrictions on individual endpoints are noted below.

Endpoint overview

Method	Path	Roles
`GET`	`/api/orders`	All authenticated
`GET`	`/api/orders/stats`	All authenticated
`GET`	`/api/orders/:id`	All authenticated
`POST`	`/api/orders`	admin, mesero, cajero
`PUT`	`/api/orders/:id/items`	admin, mesero
`PUT`	`/api/orders/:id/status`	All authenticated
`DELETE`	`/api/orders/:id/items/:itemId`	admin, mesero

GET /api/orders

Returns a flat array of all orders with their line items and calculated totals, sorted by creation time descending.

curl https://your-api-host/api/orders \
  -H "Authorization: Bearer <token>"

GET /api/orders/stats

Returns aggregated sales statistics used by the management dashboard. Query parameters

Parameter	Type	Description
`range`	`week` \| `month`	`week` (default) returns the last 7 days; `month` returns all days in the current calendar month.

# Weekly stats (default)
curl "https://your-api-host/api/orders/stats" \
  -H "Authorization: Bearer <token>"

# Monthly stats
curl "https://your-api-host/api/orders/stats?range=month" \
  -H "Authorization: Bearer <token>"

Stats response fields

weekly

array

Array of daily sales totals sorted chronologically.

Show weekly item

day

string

Abbreviated weekday name (Lun, Mar, …) for range=week, or the numeric day of month ("1", "2", …) for range=month.

sales

number

Total revenue for that day across all non-cancelled orders.

date

string

ISO date string YYYY-MM-DD. Days with no orders are filled in with sales: 0.

topProducts

array

Up to 5 best-selling products over the last 7 days.

Show topProducts item

name

string

Product name.

quantity

number

Total units sold.

value

number

Total revenue generated by this product.

today

object

Show today object

orders

number

Number of orders created today.

sales

number

Total revenue today (paid and pending orders).

GET /api/orders/:id

Returns a single order with full line-item details.

curl https://your-api-host/api/orders/42 \
  -H "Authorization: Bearer <token>"

Returns 404 if the order does not exist.

POST /api/orders

Creates a new order, inserts line items, optionally records a payment method, and sets the table status to ocupada. If a reservation exists for the same table today, it is automatically linked and marked completada. Roles: admin, mesero, cajero

Request body

mesa_id

number

required

ID of the table being served. The table must exist. After creation the table’s estado is set to ocupada.

mesero_id

number

required

ID of the waiter (usuario) responsible for this order.

items

array

required

One or more line items. Each element must include producto_id and cantidad. Items with missing fields are silently skipped.

Show item object

producto_id

number

required

ID of the menu product.

cantidad

number

required

Quantity ordered. Must be ≥ 1.

precio_unitario

number

Override price. If omitted, the current product price from the database is used.

observaciones

string

Per-item notes (e.g. “sin cebolla”).

observaciones

string

General notes for the entire order.

cliente_id

number

ID of an existing customer record to associate with this order.

reserva_id

number

ID of an existing reservation to link. If omitted, the server looks for any confirmada or pendiente reservation for this table today and links it automatically.

metodo_pago

string

Payment method. Accepted values: efectivo, tarjeta, qr, transferencia. When provided a payment record is created immediately and estado_pago is set to pagado.

Example request

curl -X POST https://your-api-host/api/orders \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mesa_id": 3,
    "mesero_id": 5,
    "items": [
      { "producto_id": 12, "cantidad": 2 },
      { "producto_id": 7,  "cantidad": 1, "observaciones": "sin sal" }
    ],
    "observaciones": "Cumpleaños, por favor traer postre de cortesía",
    "cliente_id": 8
  }'

Example response

{
  "id": 101,
  "message": "Pedido creado correctamente"
}

PUT /api/orders/:id/items

Adds new line items to an existing order or updates the quantity of existing ones. Existing items are identified by their id field; objects without id are inserted as new items. Roles: admin, mesero

curl -X PUT https://your-api-host/api/orders/101/items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": 55, "producto_id": 12, "cantidad": 3 },
      { "producto_id": 9, "cantidad": 1 }
    ]
  }'

PUT /api/orders/:id/status

Updates the service status of an order. When the order transitions to delivered or cancelled, the associated table’s estado is automatically set back to libre. A notification is also dispatched to the relevant staff role. Roles: All authenticated

Request body

status

string

required

English status string. Accepted values and their internal equivalents:

English (`status`)	Spanish (`estado_servicio`)	Triggers table `libre`
`pending`	`pendiente`	No
`preparing`	`preparando`	No
`ready`	`listo`	No
`delivered`	`entregado`	Yes
`cancelled`	`cancelado`	Yes

Example request

curl -X PUT https://your-api-host/api/orders/101/status \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "preparing" }'

DELETE /api/orders/:id/items/:itemId

Removes a single line item from an order. Roles: admin, mesero

curl -X DELETE https://your-api-host/api/orders/101/items/55 \
  -H "Authorization: Bearer <token>"

Returns 404 if itemId does not exist.

Order response object

The following fields are returned by GET /api/orders and GET /api/orders/:id.

number

Unique order ID.

mesa_id

number

ID of the table.

mesa_numero

number

Human-readable table number.

cliente_id

number | null

Linked customer ID, if any.

cliente_nombre

string | null

Linked customer’s name, if any.

reserva_id

number | null

Linked reservation ID, if any.

mesero_id

number

ID of the assigned waiter.

mesero_nombre

string

Full name of the assigned waiter.

estado_servicio

string

Current service status in Spanish: pendiente, preparando, listo, entregado, or cancelado.

estado_pago

string

Payment status: pendiente, pagado, or anulado.

metodo_pago

string | null

Payment method recorded, if paid.

observaciones

string | null

General order notes.

subtotal

number

Sum of all line-item subtotals.

total

number

Same as subtotal (tax not applied at the API level).

time

string

Creation time formatted as HH:MM in es-ES locale.

creado_en

string

Full ISO timestamp of order creation.

status

string

English-mapped service status: pending, preparing, ready, delivered, or cancelled.

items

array

Line items belonging to this order.

Show items array

number

Line-item ID.

producto_id

number

Product ID.

nombre

string

Product name at time of order.

cantidad

number

Quantity ordered.

precio_unitario

number

Unit price charged.

subtotal

number

cantidad × precio_unitario.

estado

string

Item-level status.

observaciones

string | null

Per-item notes.

Full example order response

{
  "id": 101,
  "mesa_id": 3,
  "mesa_numero": 3,
  "cliente_id": 8,
  "cliente_nombre": "Ana Torres",
  "reserva_id": null,
  "mesero_id": 5,
  "mesero_nombre": "Luis Pérez",
  "estado_servicio": "preparando",
  "estado_pago": "pendiente",
  "metodo_pago": null,
  "observaciones": "Cumpleaños, por favor traer postre de cortesía",
  "subtotal": 245.50,
  "total": 245.50,
  "time": "13:22",
  "creado_en": "2024-06-15T13:22:04.000Z",
  "status": "preparing",
  "items": [
    {
      "id": 210,
      "producto_id": 12,
      "nombre": "Pasta Carbonara",
      "cantidad": 2,
      "precio_unitario": 95.00,
      "subtotal": 190.00,
      "estado": "pendiente",
      "observaciones": null
    },
    {
      "id": 211,
      "producto_id": 7,
      "nombre": "Sopa del Día",
      "cantidad": 1,
      "precio_unitario": 55.50,
      "subtotal": 55.50,
      "estado": "pendiente",
      "observaciones": "sin sal"
    }
  ]
}

Authentication

Restaurant Operations

Billing & Reporting

Administration

Orders API — Create, Update, and Track Restaurant Orders

Endpoint overview

GET /api/orders

GET /api/orders/stats

Stats response fields

GET /api/orders/:id

POST /api/orders

Request body

Example request

Example response

PUT /api/orders/:id/items

PUT /api/orders/:id/status

Request body

Example request

DELETE /api/orders/:id/items/:itemId

Order response object

Full example order response

Build docs developers (and LLMs) love

Authentication

Restaurant Operations

Billing & Reporting

Administration

Documentation Index

​Endpoint overview

​GET /api/orders

​GET /api/orders/stats

​Stats response fields

​GET /api/orders/:id

​POST /api/orders

​Request body

​Example request

​Example response

​PUT /api/orders/:id/items

​PUT /api/orders/:id/status

​Request body

​Example request

​DELETE /api/orders/:id/items/:itemId

​Order response object

​Full example order response

Build docs developers (and LLMs) love

Endpoint overview

GET /api/orders

GET /api/orders/stats

Stats response fields

GET /api/orders/:id

POST /api/orders

Request body

Example request

Example response

PUT /api/orders/:id/items

PUT /api/orders/:id/status

Request body

Example request

DELETE /api/orders/:id/items/:itemId

Order response object

Full example order response