The fields
A booking’s time is described by three input fields:
And four derived local fields that the server computes for you:
Why both?
UTC is the only sane storage format — but a client thinks in “Tuesday at 1pm in New York.” Storing both:- Keeps the math correct across DST transitions, region changes, and multi-day bookings.
- Lets list endpoints filter by UTC windows without expanding every row.
- Lets the dashboard and your UI display the booking exactly as the client scheduled it, without re-deriving the timezone on every read.
Server derives, you do not
When you create or reschedule a booking, you supply only the UTC instants andbookingTz. The server computes the four local fields
using bookingTz as the source of truth and writes them alongside.
Local fields you send in a request body are silently ignored, on create
and on PATCH alike. The request succeeds, and the server’s derived
values win — you cannot override what the server derives.
If you change bookingTz on a reschedule, the local fields are
re-derived automatically.
Querying by date
List endpoints that filter on time accept UTC bounds only:startDate and endDate must be full ISO 8601 datetimes ending in Z.
A bare date (2026-06-01) or a datetime with an offset
(2026-06-01T00:00:00-04:00) is a 400 VALIDATION_ERROR. Convert to UTC
first — Date.prototype.toISOString() always produces the right form.
There is no localDate filter. If you want “all bookings on Tuesday in
New York,” compute the UTC window yourself:
Bookings that started before your window but end inside it are not
included by a naive UTC filter — expand the window backward by your
longest expected booking duration if you need to catch overnight or
multi-day bookings.
Availability slot times
Availability responses describe each slot’s start twice, and both fields always denote the same instant:
The response
timezone is the zone actually used for rendering and day
bucketing — the request timezone, or the project default when you sent
none. POST …/availability/suppliers uses startUtc / startLocal for the
same pair. Around a daylight-saving change a supplier’s weekly schedule keeps
its local wall clock (a 9:00 lesson stays 9:00 in the supplier’s zone) and
the UTC instant shifts; that is correct, so do not “fix” it on your side.
See Availability → Slot times and zones.
Valid timezones
Every zone field on a write is validated the same way. Accepted: any IANA identifier containing a/ (America/Toronto, Australia/Sydney,
Asia/Kolkata) and the literal UTC. Deprecated aliases that contain a /
(US/Pacific, Canada/Eastern) still pass. Rejected with a 400:
abbreviations (EST, PST, IST, CET), legacy names without a /
(Hongkong, Japan, Zulu), numeric offsets (-05:00, UTC+5), and
values with leading or trailing whitespace.
The error envelope names the field in its message:
America/New_York, not EST;
Europe/London, not BST. Values already stored are not re-validated on
read.