The Day — one merchant-local date's departures, parties, riders, readiness and balances
const url = 'https://quikstik-core.fly.dev/days/2026-04-15';const options = { method: 'GET', headers: { 'x-tenant-id': '2489E9AD-2EE2-8E00-8EC9-32D5F69181C0', Authorization: 'Bearer <token>' }};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://quikstik-core.fly.dev/days/2026-04-15 \ --header 'Authorization: Bearer <token>' \ --header 'x-tenant-id: 2489E9AD-2EE2-8E00-8EC9-32D5F69181C0'The one read the operator app’s Day tab, the Now tab’s “next departure” header and the conditions card render from. Rust composes it; the client does no grouping, counting or per-booking calls. Commerce-rooted (departures, bookings, obligations and agreements are the spine) even though it joins participants rosters/readiness, open threads, capacity and conditions — each leg is a batch read, so the SQL statement count does not grow with the number of bookings.
date is the merchant-local civil date (YYYY-MM-DD) in tz, the tenant’s one catalog time
zone; the day is [local 00:00, next local 00:00). A tenant whose catalog declares no single
zone answers 409 time_zone_unresolved rather than a guess.
Ordering: departures by start_at_ms; parties by lead display_name (case-insensitive).
Counting law: cancelled bookings are listed in parties with status: cancelled (the
operator must see who dropped) and add nothing to riders, party_count, readiness,
balance_due_minor or totals. A cancelled departure is listed with status: cancelled and
contributes nothing either. A scheduled departure with no live parties still appears.
next_departure is the earliest scheduled departure on the date with
start_at_ms >= now_ms, else null.
meeting_point is the departure’s (else its variant’s). A party’s agreed_start_at_ms /
agreed_meeting_point appear only when its agreement differs from the departure and are never written onto the departure.
A party carries channel_ref (the OTA’s own booking reference, e.g. BR-1453533133) when the
booking has one; absent otherwise.
party.balance.due_minor equals GET /obligations/{obligation_ref}/balance. Dues sum only
within one currency: live parties in two currencies answer 409 mixed_currency.
Readiness folds the participants engine: blocked = a required requirement has a current
attestation that fails it, missing = a required requirement has none (or only under a stale
policy), else ready; missing lists the unmet requirement kinds.
Auth: a session, or an operator key scoped bookings.read.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Merchant-local civil date, YYYY-MM-DD.
Header Parameters
Section titled “Header Parameters”Tenant identifier (UUID).
Authn/authz semantics are intentionally TBD for this contract slice; this header exists to keep the contract explicitly multi-tenant from day 0.
Responses
Section titled “Responses”The day
object
Merchant-local civil date.
The tenant’s IANA zone the date is read in.
Server clock the read was computed at, Unix ms.
Earliest scheduled departure with start_at_ms >= now_ms, else null.
object
object
Start + the variant’s duration, when known.
The departure’s (else its variant’s); per-booking overrides stay on the party.
object
The departure’s pool; null when no pool is provisioned.
object
Dep:{departure_id}
Max(0, target - committed)
From conditions_states; null when the departure is not scored.
object
The rule that fired, when the state came from one.
Riders on live parties.
Live (non-cancelled) parties; the listing is parties.
object
Sum of live parties’ due, minor units.
ISO 4217, present when any live party carries a balance.
object
QS-XXXXXXXX, or the OTA’s VIA-… / GET-… number.
The OTA’s own booking reference (BR-…, GYG-…), normalised; absent when the booking has none. Added 2026-10-26 (#932) — undeclared until 2026-10-27, which broke strict clients.
object
Buyer name, else the first rider’s, else the reference.
object
The person behind the roster row; omitted when the row has none.
The person’s room; present iff person_id is.
object
Unmet required requirement kinds; empty iff readiness is ready.
Only when the agreement’s start differs from the departure’s.
Only when the agreement’s place differs from the departure’s.
object
Null when the booking has no obligation row.
object
Gross - settled; equals GET /obligations/{ref}/balance.
The party’s open (not closed, not archived) thread.
A held reply on that thread, awaiting approval.
The booking’s room: open GET /rooms/booking/{ref_id} with no second lookup.
object
object
Scheduled departures.
Live parties.
Example
{ "departures": [ { "status": "scheduled", "conditions": { "state": "ride" }, "parties": [ { "status": "created", "channel": "direct", "participants": [ { "room": { "ref_type": "person" }, "readiness": "ready", "missing": [ "waiver" ] } ], "room": { "ref_type": "booking" } } ] } ]}Invalid_session
Operator key without bookings.read
Time_zone_unresolved (no single catalog zone) or mixed_currency
object
Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).
Example
{ "reason": "sold_out"}Invalid_date
object
Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).
Example
{ "reason": "sold_out"}Days_unavailable (a leg is not wired or failed; no partial answer is served)
object
Stable, machine-readable reason code (e.g. “sold_out”, “processor_not_configured”, “rail_refused”).
Example
{ "reason": "sold_out"}