Skip to main content
Booking times in MarketBox are stored as explicit UTC instants plus an IANA timezone identifier. Local-time fields exist for convenience — they’re derived on the server, not provided by clients.

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 and bookingTz. 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:
Use the canonical zone name — America/New_York, not EST; Europe/London, not BST. Values already stored are not re-validated on read.