List bookings by departure window, confirmation number, buyer email, or free text

GET

/bookings

curl --request GET \
  --url https://quikstik-core.fly.dev/bookings \
  --header 'Authorization: Bearer <token>'

• Production

Live operator read (session, or an operator key scoped bookings.read). Exactly ONE selector: the window pair (window_start + window_end), ref, email, or q. Two selectors answer 422 conflicting_selectors. Every selector answers the same window-shaped rows; cancelled bookings ride along with status: cancelled (the caller filters).

• ref — the guest’s QS-XXXXXXXX confirmation number (obligation-ref hex prefix).
• email — case-insensitive exact match on the buyer’s notify_email.
• q — case-insensitive substring over buyer name, buyer email and rider display names (riders found through the roster of either the obligation or the booking). At least 3 characters, else 422 query_too_short.

email and q return at most 100 rows, newest departure first.

Authorizations

• bearerAuth

Parameters

Query Parameters

window_start

string format: date-time

Required together with window_end when no other selector is given.

window_end

string format: date-time

ref

string

Guest confirmation number, e.g. QS-F395741B (case-insensitive).

email

string

Buyer email, case-insensitive exact match.

q

string

>= 3 characters

Free text, minimum 3 characters.

Responses

200

Bookings with departures in the window

Media typeapplication/json

Array<object>

BookingDto plus departure_start_time, and — when the booking’s agreement carries them — agreed_start_time (RFC3339, only when it differs from the departure) and agreed_meeting_point {name, address}. These are booking facts (a delivery address, a named meet-up place, an amended time) and override the departure row on any sheet; their absence means the departure is the truth. Added 2026-09-25: a departure row is shared (resolved on variant + start time), so per-booking place/time must never be written to it.

object

Example ^generated

[
  {}
]

401

Invalid_session

422

Invalid_window, invalid_reference, invalid_email, query_too_short, or conflicting_selectors

Media typeapplication/json

object

reason

required

Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).

string

Example

{
  "reason": "sold_out"
}

503

Backend unavailable