Walk-in queues and waitlists

Use a walk-in queue when customers arrive without a booking, and a waitlist when no slot suits the customer now. Both are enabled per definition and both can be resolved by creating an appointment and linking it back. For the model behind them, see the Appointments concept. All endpoints are bearer authenticated and live under https://api.[tenant].getomneo.com/api/v3.

Flow	Enabled by	Use when
Walk-in queue	`allow_queue` (and `walk_in_only` definitions)	The customer is at the location now and wants to be seen in order of arrival.
Waitlist	`allow_waitlist`	No suitable slot is available, and the customer wants to be contacted when one opens.

Walk-in queue

Check a customer into the queue for a definition that allows walk-ins. Send a POST to /appointment-queues with the definition and location. Omit profile_id for an anonymous walk-in.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-queues" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_definition_id": 1,
    "location_id": 13,
    "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
    "notes": "Walk-in, wants a fitting"
  }'

The response is 201. For an anonymous walk-in, drop profile_id:

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-queues" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "appointment_definition_id": 1, "location_id": 13 }'

The entry returns wrapped in a data object, with status defaulting to waiting and appointment_id still null:

{
  "data": {
    "id": 812,
    "appointment_definition_id": 1,
    "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
    "profile": {
      "id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    },
    "location_id": 13,
    "location": {
      "id": 13,
      "name": "Melbourne Central",
      "handle": "melbourne-central",
      "timezone": "Australia/Melbourne"
    },
    "staff_id": null,
    "staff": null,
    "appointment_id": null,
    "status": "waiting",
    "notes": "Walk-in, wants a fitting",
    "meta": {},
    "created_at": "2026-05-11T00:05:00Z",
    "updated_at": "2026-05-11T00:05:00Z"
  }
}

For an anonymous walk-in, profile_id, profile, staff_id, and staff are null.

Field	Type	Notes
`appointment_definition_id`	integer	Required. The definition the walk-in is for.
`location_id`	integer	Required. Where the customer checked in.
`profile_id`	string or null	Profile UUID. Omit for an anonymous walk-in.
`staff_id`	string or null	Assign a staff member to the entry.
`status`	enum	`waiting`, `called`, `served`, or `cancelled`. Defaults to `waiting`.
`appointment_id`	integer or null	The linked appointment, set when converting a served entry.
`notes`	string or null	Free-text note.
`meta`	object	Custom key/value data.
`id`	integer	Response only. The queue entry’s id.
`profile`	object or null	Response only. `{ id, first_name, last_name, email }`, `null` for an anonymous walk-in.
`location`	object	Response only. `{ id, name, handle, timezone }`.
`staff`	object or null	Response only. The assigned staff member, when one is set.
`created_at`, `updated_at`	string	Response only. UTC timestamps.

A queue entry moves through four statuses.

waiting -> called -> served
        -> cancelled

Status	Meaning
`waiting`	The customer has checked in and is in line. This is the default on create.
`called`	The customer has been called to be seen.
`served`	The customer has been seen.
`cancelled`	The customer left the queue without being served.

Advance the status with a PUT to /appointment-queues/{id}:

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-queues/{queueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "called" }'

Converting a served entry into an appointment

To keep a record of the service, create an appointment and link it to the queue entry through the appointment_id field. Create the appointment first, then set appointment_id on the queue entry:

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-queues/{queueId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "served", "appointment_id": 5012 }'

The queue entry now points at the appointment, so the walk-in and its resulting booking are tied together.

Waitlist

Register a customer’s interest when no slot suits. Send a POST to /appointment-waitlists. profile_id is required here (a waitlist entry always belongs to a known Profile). Include desired_start_at to record when the customer would like to be seen.

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-waitlists" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_definition_id": 1,
    "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
    "location_id": 13,
    "desired_start_at": "2026-05-18 10:00:00",
    "notes": "Prefers a morning slot"
  }'

The entry returns wrapped in a data object, with status defaulting to active:

{
  "data": {
    "id": 415,
    "appointment_definition_id": 1,
    "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
    "profile": {
      "id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    },
    "location_id": 13,
    "location": {
      "id": 13,
      "name": "Melbourne Central",
      "handle": "melbourne-central",
      "timezone": "Australia/Melbourne"
    },
    "appointment_id": null,
    "status": "active",
    "desired_start_at": "2026-05-18T10:00:00Z",
    "notes": "Prefers a morning slot",
    "meta": {},
    "created_at": "2026-05-11T00:10:00Z",
    "updated_at": "2026-05-11T00:10:00Z"
  }
}

Field	Type	Notes
`appointment_definition_id`	integer	Required. The definition the customer is waiting for.
`profile_id`	string	Required. A waitlist entry always belongs to a known Profile.
`location_id`	integer	Where the customer wants to be seen.
`desired_start_at`	string or null	When the customer would like to be seen.
`status`	enum	`active`, `fulfilled`, or `cancelled`. Defaults to `active`.
`appointment_id`	integer or null	The linked appointment, set when fulfilling the entry.
`notes`	string or null	Free-text note.
`meta`	object	Custom key/value data.
`id`	integer	Response only. The waitlist entry’s id.
`profile`	object	Response only. `{ id, first_name, last_name, email }`.
`location`	object	Response only. `{ id, name, handle, timezone }`.
`created_at`, `updated_at`	string	Response only. UTC timestamps.

A waitlist entry moves through three statuses.

active -> fulfilled
       -> cancelled

Status	Meaning
`active`	The customer is waiting for a slot. This is the default on create.
`fulfilled`	A slot opened and the entry became an appointment.
`cancelled`	The customer no longer wants a slot.

Fulfilling a waitlist entry

When a slot opens, create an appointment for the customer, then fulfil the entry by linking the appointment through appointment_id and setting the status to fulfilled:

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-waitlists/{waitlistId}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "fulfilled", "appointment_id": 5012 }'

Filtering queues and waitlists

Both lists support the same filter pattern as the rest of the API. Filter by definition, location, and status to build an operator view for one service at one store.

# Everyone waiting in the queue for one service at one location
GET /api/v3/appointment-queues?filter[appointment_definition_id]=1&filter[location_id]=13&filter[status]=waiting

# Active waitlist entries for one service
GET /api/v3/appointment-waitlists?filter[appointment_definition_id]=1&filter[status]=active

Filter	Applies to	Example
`appointment_definition_id`	Both	`filter[appointment_definition_id]=1`
`location_id`	Both	`filter[location_id]=13`
`status`	Queue: `waiting`, `called`, `served`, `cancelled`. Waitlist: `active`, `fulfilled`, `cancelled`.	`filter[status]=waiting`
`profile_id`	Both	`filter[profile_id]={profileId}`

Both list endpoints are paginated. Use page[size] and page through meta.pagination, the same as every other Omneo list endpoint.

End-to-end example: a walk-in becomes a booked service

This is the full arc for a customer who arrives without a booking and is served.

Check the customer in

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointment-queues" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "appointment_definition_id": 1, "location_id": 13, "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02" }'

The entry is created with status: "waiting" and an id (here 812).

Call the customer

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-queues/812" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "called" }'

Create the appointment for the service

curl -X POST "https://api.[tenant].getomneo.com/api/v3/appointments" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "appointment_definition_id": 1,
    "profile_id": "a1b460b2-953f-4587-b4eb-fb0f29b55e02",
    "location_id": 13,
    "scheduled_start_at": "2026-05-11 10:15:00",
    "scheduled_end_at": "2026-05-11 10:45:00",
    "timezone": "Australia/Melbourne"
  }'

Take the appointment id from the 201 response.

Mark served and link the appointment

curl -X PUT "https://api.[tenant].getomneo.com/api/v3/appointment-queues/812" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "status": "served", "appointment_id": 5012 }'

The queue entry now points at the appointment, tying the walk-in to its booking. A waitlist entry follows the same shape: create the appointment, then PUT the entry with status: "fulfilled" and appointment_id.

Response codes

Method	Endpoint	Success	Errors
`POST`	`/appointment-queues`, `/appointment-waitlists`	`201`	`401`, `403`, `422`
`GET`	`.../{id}`	`200`	`401`, `403`, `404`
`PUT`	`.../{id}`	`200`	`401`, `403`, `404`, `422`
`DELETE`	`.../{id}`	`204`	`401`, `403`, `404`

Errors

Status	When
`401`	Missing or invalid bearer token.
`403`	The token lacks the required scope, or the actor lacks permission.
`404`	The queue or waitlist entry does not exist.
`422`	Validation failed, for example a missing `appointment_definition_id`, a waitlist create without a `profile_id`, or an invalid `status`.

Edge cases and gotchas

Anonymous walk-ins have no Profile. Omit profile_id on a queue create for a walk-in you cannot identify. The waitlist always requires profile_id, because an entry has to belong to a known customer so you can contact them.
Linking is the source of truth, not conversion. Nothing converts a queue or waitlist entry automatically. You create the appointment yourself, then set appointment_id on the entry and move its status.
Statuses differ between the two. A queue moves through waiting, called, served, cancelled; a waitlist through active, fulfilled, cancelled. Filter with the values that belong to each resource.
Deleting removes the entry. DELETE returns 204 and no body. To keep the record, set status to cancelled instead.

Core setup

Profiles and data

Commerce

Incentives

Reactions

Webhooks and events

Frontend & SDK

POS integration

Appointments

Lists

Groups

Feedback

Extensions

Walk-in queues and waitlists

Walk-in queue

Converting a served entry into an appointment

Waitlist

Fulfilling a waitlist entry

Filtering queues and waitlists

End-to-end example: a walk-in becomes a booked service

Response codes

Errors

Edge cases and gotchas

​Walk-in queue

​Converting a served entry into an appointment

​Waitlist

​Fulfilling a waitlist entry

​Filtering queues and waitlists

​End-to-end example: a walk-in becomes a booked service

​Response codes

​Errors

​Edge cases and gotchas

​Related

Walk-in queue

Converting a served entry into an appointment

Waitlist

Fulfilling a waitlist entry

Filtering queues and waitlists

End-to-end example: a walk-in becomes a booked service

Response codes

Errors

Edge cases and gotchas

Related