Update Order Status

After processing an order (e.g., sending it to the kitchen, completing fulfillment), update the order state on the iorder server. This records the outcome; the integration must separately prevent duplicate external processing.

Acknowledge a processed order

1. Confirm the order number and reconcile the register's processing result.
2. Persist that result in the integration.
3. Send the appropriate state and a useful non-sensitive comment.
4. Check both the HTTP response and returned state; a reported failure can return to PLACED below the configured threshold.
5. If the response is lost, reconcile before repeating external processing.

Endpoint

PUT https://{host}/orders/{orderId}/statusupdate

Path parameters:

Parameter	Type	Description
orderId	string	The order number (as a string)

Headers:

Header	Required	Description
api_key	Yes	Service device API key
Content-Type	Yes	application/json

Request body: OrderUpdate

{
  "newState": "COMPLETED",
  "comment": "Order delivered to table A12"
}

Request Schema

OrderUpdate

Field	Type	Required	Description
newState	string	Yes	Target order state (see valid values below)
comment	string or null	No	Optional comment or message (stored as order message)

Valid newState Values

Value	Description
SELECTING	Customer is selecting items
NEW	Newly created order
PLACED	Order has been submitted by customer
COMPLETED	Order was fulfilled successfully
ABORTED	Order was cancelled
FAILED	Order processing failed

Lifecycle and failure handling

Service integrations normally acknowledge a placed order as COMPLETED, cancel it as ABORTED, or report FAILED. The endpoint accepts an OrderState without checking the previous state against a transition table. Do not use status changes as a reservation or compare-and-set lock.

Reporting FAILED increments the failure count. Below the license's configured threshold, the resulting state is immediately PLACED for retry; at the threshold it remains FAILED and staff are alerted. Inspect the returned state rather than assuming it equals the requested state.

Operators can inspect GET /orders/failed and use POST /orders/{orderId}/retry or POST /commands/{id}/retry for recovery with the required access. Manual retry resets the failure count. See Messages for the staff workflow.

Response

Success: 200 OK with the updated Order DTO:

{
  "number": 12345,
  "userNumber": 5,
  "rows": [
    {
      "category": {
        "order": 1,
        "id": 1,
        "description": "Beverages"
      },
      "itemType": "MENU_ITEM",
      "name": "Espresso",
      "number": 1,
      "factor": 2,
      "price": 3.50,
      "priceTogo": null,
      "discount": null,
      "subrows": null
    }
  ],
  "state": "COMPLETED",
  "orderTime": "10:30:00",
  "completeTime": "10:35:00",
  "tableNumber": "A12",
  "deviceNames": "service-device-1",
  "message": "Order delivered to table A12",
  "version": 2
}

The state field reflects the new state. The completeTime is populated automatically by the server when transitioning to COMPLETED or ABORTED.

Curl Examples

Success: Mark Order as Completed

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "COMPLETED", "comment": "Order delivered to table A12"}' \
  "https://{host}/orders/12345/statusupdate"

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "number": 12345,
  "state": "COMPLETED",
  ...
}

Success: Abort an Order

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "ABORTED", "comment": "Customer cancelled"}' \
  "https://{host}/orders/12345/statusupdate"

Invalid state name

Use only the enum names listed above. An unknown name such as NOT_A_STATE is invalid. Check the error response returned by your deployed API version.

Order Not Found

curl -i -X PUT \
  -H "api_key: abc123-def456-ghi789" \
  -H "Content-Type: application/json" \
  -d '{"newState": "COMPLETED"}' \
  "https://{host}/orders/99999/statusupdate"

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "about:blank",
  "title": "Illegal argument",
  "status": 400,
  "detail": "Order does not exist",
  "instance": "/orders/99999/statusupdate"
}

Duplicate and concurrent updates

Repeating a status update is not automatically rejected because the state has already changed. Persist the order number and processing outcome in the integration and coordinate multiple workers before sending an order to an external system. A successful status update does not prove exclusive ownership, and a lost response does not prove the operation failed.

Do not assume that this endpoint transparently retries optimistic-lock conflicts. Inspect the response and reconcile the processing outcome before repeating an external action.

Error Handling

Status	Meaning
200	Order status updated successfully
400	Invalid request or order does not exist
401	Unauthorized (invalid or expired API key)
409	Optimistic locking conflict (another device modified the order concurrently)

Handle conflicts according to the actual response from the deployed API; do not rely on an automatic three-attempt retry for this endpoint.

Next Steps

• Respond to Commands — Send responses to commands received via polling
• Error Handling — Understand error response formats and edge cases