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 tells the system the order has been handled and prevents duplicate 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
PLACED	Order has been submitted by customer
COMPLETED	Order was fulfilled successfully
ABORTED	Order was cancelled
FAILED	Order processing failed

Valid State Transitions

The iorder system tracks orders through a defined lifecycle. Not all transitions are valid.

                    +---> COMPLETED
                    |
  PLACED -----------+
                    |
                    +---> ABORTED

  SELECTING -------> ABORTED

  PLACED ----------> FAILED

  FAILED ----------> PLACED (retry)

Valid transitions for service clients:

From	To	Description
PLACED	COMPLETED	Order fulfilled (most common)
PLACED	ABORTED	Order cancelled after being placed
PLACED	FAILED	Backend processing error
SELECTING	ABORTED	Customer session closed with no order placed

The FAILED state is special: orders in FAILED state are retried by a scheduled job that resets them back to PLACED. After that, the client can attempt processing again.

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 Transition

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

Response:

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

{
  "type": "about:blank",
  "title": "Illegal argument",
  "status": 400,
  "detail": "No enum constant com.ridme.pos.model.enums.OrderState.SELECTING",
  "instance": "/orders/12345/statusupdate"
}

Note: The error uses ProblemDetail (RFC 7807) format.

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 Idempotent Updates

The status update endpoint is not inherently idempotent. If you send the same status update twice, the second call will fail because the order's state has already changed from the original state. To handle this:

• Track which orders you have already processed using the order number as an idempotency key.
• Only send status updates for orders you have not yet processed.
• If a status update fails with a 400 error, check the current order state via polling before retrying.

Error Handling

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

For 409 conflicts, the server implements automatic retry with up to 3 attempts. If the conflict persists, the client should refresh its view of the order and retry.

Next Steps

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