Ring customers from your own POS.

1. 1

   Create a key

   Open Connect in your dashboard and create an API key. Start with a test key.

2. 2

   Create a ticket per order

   POST /tickets with reference set to your invoice number. Print the qr_url on the receipt or show it on screen.

3. 3

   Mark it ready

   POST /tickets/by-reference/{ref}/ready. The phone rings. No ids to store on your side.

Create a ticket

curl https://kueues.com/api/v1/tickets \
  -H "Authorization: Bearer $KUEUES_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-INV-1043" \
  -d '{"reference": "INV-1043", "customer_name": "Sam"}'

HTTP/1.1 201 Created
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1792000980

{
  "ticket": {
    "object": "ticket",
    "id": "q7Rk2LmP9sXc4VbN",
    "number": 27,
    "status": "preparing",
    "reference": "INV-1043",
    "customer_name": "Sam",
    "note": null,
    "source": "api",
    "test": false,
    "claimed": false,
    "alerts_on": false,
    "customer_coming": false,
    "claim_url": "https://kueues.com/t/7KQ2MXR9PA",
    "qr_url": "https://kueues.com/api/v1/qr/7KQ2MXR9PA",
    "business_day": "2026-10-14",
    "queue": { "id": "Mq3vT8kLp2Wd", "name": "Pickup counter", "room": null },
    "pos": null,
    "created_at": "2026-10-14T17:02:11Z",
    "claimed_at": null,
    "ready_at": null,
    "collected_at": null,
    "cancelled_at": null,
    "expired_at": null
  },
  "created": true
}

Mark it ready by reference

curl -X POST https://kueues.com/api/v1/tickets/by-reference/INV-1043/ready \
  -H "Authorization: Bearer $KUEUES_KEY"

HTTP/1.1 200 OK

{
  "ticket": {
    "object": "ticket",
    "id": "q7Rk2LmP9sXc4VbN",
    "number": 27,
    "status": "ready",
    "reference": "INV-1043",
    "ready_at": "2026-10-14T17:09:03Z",
    ...
  },
  "changed": true
}

Every request except GET /qr/{token} carries a location API key as a bearer token: Authorization: Bearer kq_live_…. Each key belongs to one location and can be limited to specific queues.

A reference is your own order or invoice number. Send it on create and you can act on the ticket later without storing our id.

• Up to 64 characters: letters, digits, space and _ - . / # :. Matching ignores case for Latin letters, so inv-1043 finds INV-1043.
• Creating a ticket with a reference that is still open in that queue returns the existing ticket with 200 and created: false. A new ticket returns 201 and created: true.
• Lookups by reference prefer an open ticket, then one from today's business day (days start at 05:00 location time), then the most recent.
• Percent-encode references in paths. # becomes %23 and / becomes %2F, so A/12#3 is A%2F12%233.

Idempotency-Key

For creates without a reference (or for extra safety on flaky networks), send an Idempotency-Key header: up to 255 visible ASCII characters, remembered for 24 hours. A retry with the same key and body returns the original result. The same key with a different body returns 409 idempotency_conflict.

State changes are idempotent by design. Calling ready, collect or cancel on a ticket already in that state returns 200 with changed: false. collect is also allowed straight from preparing, for orders handed over without a ring.

A location can run several queues: departments, pickup windows, the bar and the kitchen. GET /shop lists the queues your key can use. When there is more than one, send queue with the queue id on create.

curl https://kueues.com/api/v1/shop \
  -H "Authorization: Bearer $KUEUES_KEY"

HTTP/1.1 200 OK

{
  "shop": {
    "code": "H7K2QM",
    "name": "Lucky Noodle Bar",
    "open": true,
    "timezone": "America/Chicago",
    "business_day": "2026-10-14",
    "subscription_active": true
  },
  "queues": [
    { "id": "Mq3vT8kLp2Wd", "name": "Pickup counter", "room": null },
    { "id": "Zp8cR2nVx4Ht", "name": "Bar", "room": "Patio" }
  ],
  "key": { "id": "k9Wm2Qx7Lr4T", "test": false, "all_queues": true }
}

• Numbers restart at 1 in each queue every business day, so the number alone is not unique. Join on id or reference.
• There is one webhook endpoint per location. Route events by data.ticket.queue.

All paths are relative to https://kueues.com/api/v1. Request bodies are JSON with Content-Type: application/json, up to 16 KB. The OpenAPI 3.1 spec is the source of truth.

List open tickets

curl "https://kueues.com/api/v1/tickets?status=preparing,ready&queue=Mq3vT8kLp2Wd&limit=50" \
  -H "Authorization: Bearer $KUEUES_KEY"

HTTP/1.1 200 OK

{
  "object": "list",
  "business_day": "2026-10-14",
  "tickets": [
    { "object": "ticket", "id": "q7Rk2LmP9sXc4VbN", "number": 27, "status": "ready", ... },
    { "object": "ticket", "id": "Hn4pW8sKq2ZtR6vY", "number": 26, "status": "preparing", ... }
  ]
}

Errors share one shape: { "error": { "code", "message", ... } }. Branch on code; the message is for humans and may change.

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "invalid_transition",
    "message": "This ticket is cancelled and cannot become ready.",
    "ticket_status": "cancelled"
  }
}

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "invalid_input",
    "message": "Unrecognized key: \"customer\"",
    "details": [{ "field": "(body)", "issue": "Unrecognized key: \"customer\"" }]
  }
}

Set one HTTPS endpoint per location on the Connect page, pick events, and we POST JSON to it as tickets move.

POST /webhooks/kueues HTTP/1.1
Content-Type: application/json
User-Agent: Kueues-Webhooks/1.0
Kueues-Event: ticket.ready
Kueues-Delivery: Xc2mR8kQp4LwT7vN
Kueues-Attempt: 1
Kueues-Signature: t=1792001343,v1=6f1c0e9a4b...e27d

{
  "id": "evt_3kX9pQ2mW7zR1vB8nC4d",
  "type": "ticket.ready",
  "created_at": "2026-10-14T17:09:03Z",
  "shop": { "code": "H7K2QM", "name": "Lucky Noodle Bar" },
  "data": {
    "ticket": { "object": "ticket", "id": "q7Rk2LmP9sXc4VbN", "number": 27, "status": "ready", "test": false, ... }
  }
}

Kueues-Signature looks like t=1792001343,v1=6f1c…. v1 is the hex HMAC-SHA256 of ${t}.${rawBody}, keyed with your full whsec_… secret string. Compare in constant time and reject timestamps older than 5 minutes.

import crypto from 'node:crypto'
import express from 'express'

const app = express()
const SECRET = process.env.KUEUES_WEBHOOK_SECRET // the full whsec_... string
const TOLERANCE_SEC = 300

// Raw body: the signature covers the exact bytes we sent, so do not parse JSON first.
app.post('/webhooks/kueues', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('Kueues-Signature') ?? ''
  const parts = Object.fromEntries(
    header.split(',').map((kv) => {
      const i = kv.indexOf('=')
      return [kv.slice(0, i).trim(), kv.slice(i + 1).trim()]
    }),
  )
  const t = parts.t ?? ''
  if (!/^\d+$/.test(t) || Math.abs(Date.now() / 1000 - Number(t)) > TOLERANCE_SEC) {
    return res.status(400).send('stale or missing timestamp')
  }

  const expected = crypto.createHmac('sha256', SECRET).update(`${t}.`).update(req.body).digest()
  const given = Buffer.from(parts.v1 ?? '', 'hex')
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.status(400).send('bad signature')
  }

  const event = JSON.parse(req.body.toString('utf8'))
  // Deliveries are at-least-once: skip event.id values you have already handled.
  // Then do the work (or queue it) and answer 2xx within 10 seconds.
  res.sendStatus(204)
})

app.listen(3000)

Square is a trademark of Block, Inc. Toast is a trademark of Toast, Inc. Kueues is independent and not affiliated with or endorsed by either. Integration behavior depends on what each platform's API allows and can change when they change it.