Orders API

The Orders API exposes a read-only view of every order flowing through your kiosks. It is intended for POS sync, accounting pipelines, analytics warehouses, and any integration that needs a durable record of what was sold. All endpoints live under /api/v1/orders and require a Sanctum token as described in API Authentication.

Every response is scoped to the owner behind your token. You cannot read orders from another owner even if you somehow know the ID — they return 404 Not Found.

#List orders

GET /api/v1/orders
Authorization: Bearer <token>

#Query parameters

#Response

{
  "data": [
    {
      "id": 501,
      "order_number": "YK-ABC123",
      "status": "completed",
      "payment_status": "paid",
      "payment_method": "card",
      "subtotal": 24.50,
      "tax": 2.14,
      "total": 26.64,
      "customer_name": "Alice",
      "paid_at": "2026-04-10T14:22:05+00:00",
      "created_at": "2026-04-10T14:18:44+00:00",
      "updated_at": "2026-04-10T14:22:05+00:00",
      "items": [
        {
          "id": 1201,
          "menu_item_id": 14,
          "name": "Double cheeseburger",
          "price": 8.50,
          "quantity": 2,
          "subtotal": 17.00,
          "options": [3, 7]
        }
      ]
    }
  ],
  "next_cursor": 487
}

If next_cursor is null, you have reached the end of the result set. Otherwise, pass it as ?cursor=<value> on the next request to fetch the following page.

#Fetch one order

GET /api/v1/orders/{id}
Authorization: Bearer <token>

The single-order response is the same shape as a list entry but also includes an embedded session object with kiosk metadata:

{
  "data": {
    "id": 501,
    "order_number": "YK-ABC123",
    "...": "...",
    "session": {
      "id": 9912,
      "status": "completed",
      "started_at": "2026-04-10T14:16:01+00:00",
      "ended_at": "2026-04-10T14:22:30+00:00",
      "kiosk": {
        "id": 5,
        "name": "Front counter",
        "location": "Main dining room"
      }
    }
  }
}

#Pagination strategy

Use keyset pagination by reading next_cursor and feeding it back into the next request. Keyset pagination is stable under concurrent writes — unlike page-number pagination, you will not see duplicate rows if new orders arrive while you are paging. For large historical backfills, page from cursor=0 (newest) toward older orders until the cursor comes back null.

#Polling vs webhooks

If you need real-time order delivery, use the Webhooks API — it pushes events to your endpoint within milliseconds of the order being fired. Polling this endpoint is acceptable for batch sync (hourly or nightly) but will be slower and consume more of your rate limit budget.