Polling Orders & Commands

After receiving a message event on the SSE stream, the client polls GET /orders/location to retrieve all pending orders and commands. This endpoint returns both regular orders and command objects in a single response.

Endpoint

GET https://{host}/orders/location

Headers:

Header	Required	Description
api_key	Yes	Service device API key

Query parameters:

Parameter	Type	Default	Description
orderNumber	long	0	Only return orders with number greater than this value
commandNumber	long	0	Only return commands with ID greater than this value

Response: 200 OK with body ExternalOrder[] (JSON array)

Response Schema

The endpoint returns a JSON array of ExternalOrder objects. Each object can represent either a food/beverage order or a command (e.g., read table state, request bill, export data).

ExternalOrder

{
  "number": 12345,
  "orderTime": "10:30:00",
  "tableNumber": 12,
  "userNumber": 5,
  "togo": null,
  "guestCount": 1,
  "moveTableTo": null,
  "readTableState": null,
  "paymentNumber": null,
  "receipt": null,
  "exportMainData": null,
  "paymentDiscount": null,
  "customer": null,
  "rows": [
    {
      "category": {
        "order": 1,
        "id": 1,
        "description": "Beverages"
      },
      "itemType": "MENU_ITEM",
      "name": "Espresso",
      "infotext": null,
      "number": 1,
      "factor": 2,
      "price": 3.50,
      "priceTogo": null,
      "discount": null,
      "subrows": null
    }
  ],
  "state": "PLACED"
}

Top-Level Fields

Field	Type	Description
number	long	Unique order/command identifier. Use this for idempotency and offset tracking
orderTime	string	Time the order was placed, format HH:mm:ss
tableNumber	long or null	Table number
userNumber	long or null	User number who placed the order
togo	int or null	Takeout flag indicator
guestCount	int or null	Number of guests
moveTableTo	int or null	If set, this object represents a move table command
readTableState	boolean or null	If true, this object represents a read table state command
paymentNumber	int or null	If set, this object represents a request bill command
receipt	boolean or null	If true, this object represents a print receipt command
exportMainData	boolean or null	If true, this object represents an export main data / fetch remote menu command
paymentDiscount	array or null	Array of payment discount objects applied to the order
customer	object or null	Customer information (for invoice orders)
rows	array or null	Order line items. null for commands
state	string or null	Order state. null or "PLACED" for commands

OrderRow

Field	Type	Description
category	object or null	Product category with order, id, and description
itemType	string	Type of item (MENU_ITEM, FOOD, TAKEOUT, CONDIMENTS, BEVERAGES, ARRANGEMENT)
name	string	Product name
infotext	string or null	Special instructions or notes
number	int	Row number
factor	int	Quantity
price	number or null	Unit price
priceTogo	number or null	Takeout price if different
discount	array or null	Discounts applied to this row
subrows	array or null	Sub-items (modifiers, sides)

Category

Field	Type	Description
order	int	Sort order
id	int	Category ID
description	string or null	Category name

Distinguishing Orders from Commands

The response array contains a mix of regular orders and commands. Use the isCommand() logic to differentiate them. An ExternalOrder is a command if any of these fields is set:

• readTableState is true
• moveTableTo is not null
• exportMainData is true
• paymentNumber is not null

Detection pseudo-code:

function isCommand(item) {
  return item.readTableState === true
      || item.moveTableTo !== null
      || item.exportMainData === true
      || item.paymentNumber !== null;
}

function processResponse(items) {
  for (const item of items) {
    if (isCommand(item)) {
      handleCommand(item);
    } else {
      handleOrder(item);
    }
  }
}

Command Types

Detection Field	Command Type	What To Do
readTableState: true	Read table state	Query your local table state and POST response to /commands/{id}/response
moveTableTo: <int>	Move table	Move items to the specified table number
exportMainData: true	Fetch remote menu / export data	Export your menu data (e.g., for Vectron integration)
paymentNumber: <int>	Request bill	Send the bill for the specified payment number

OrderState Enum

The state field on orders uses these values:

SELECTING  — Customer is still selecting items (not yet placed)
NEW        — Order was just created by a client application
PLACED     — Customer has submitted the order, ready for processing
ABORTED    — Order was cancelled (e.g., session closed)
FAILED     — Order processing failed in the backend system
COMPLETED  — Order was completed successfully

For polling, the endpoint returns orders with state PLACED. Commands always have state PLACED.

Polling Guidance

1. Poll on SSE message event — When the SSE stream sends a message event, call this endpoint immediately.
2. Fallback interval poll — As a safety net, poll at a reasonable interval (every 5 seconds) even without SSE notifications.
3. Use order offset — Track the highest number you have processed and pass it as orderNumber to avoid receiving already-processed orders.
4. Use command offset — Similarly, track the highest command ID and pass it as commandNumber.
5. Batch processing — You may receive multiple orders in one response. Process them in sequence, updating status for each.

Curl Examples

Success Response with Multiple Orders

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Response:

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

[
  {
    "number": 12345,
    "orderTime": "10:30:00",
    "tableNumber": 12,
    "userNumber": 5,
    "rows": [
      {
        "category": { "order": 1, "id": 1, "description": "Beverages" },
        "itemType": "MENU_ITEM",
        "name": "Espresso",
        "number": 1,
        "factor": 2,
        "price": 3.50
      }
    ],
    "state": "PLACED"
  },
  {
    "number": 12346,
    "orderTime": "10:32:00",
    "tableNumber": 5,
    "userNumber": 3,
    "rows": [
      {
        "category": { "order": 2, "id": 3, "description": "Main Course" },
        "itemType": "FOOD",
        "name": "Caesar Salad",
        "number": 1,
        "factor": 1,
        "price": 12.90
      }
    ],
    "state": "PLACED"
  }
]

With Offset Parameters (after processing)

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location?orderNumber=12346&commandNumber=42"

Empty Response (no pending items)

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Response:

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

[]

Response Containing a Command

curl -i -H "api_key: abc123-def456-ghi789" \
  "https://{host}/orders/location"

Response:

[
  {
    "number": 99,
    "orderTime": "11:05:00",
    "readTableState": true,
    "tableNumber": 12,
    "state": "PLACED"
  }
]

This is a Read Table State command for table 12. The readTableState: true indicates it is a command, not an order.

Error Handling

Status	Meaning
200	Success (may return empty array [])
401	Unauthorized (invalid or expired API key)
500	Internal server error (retry with backoff)

Next Steps

• Update Order Status — Mark orders as completed or aborted
• Respond to Commands — Send responses to commands