> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomarketbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Timezones

> How MarketBox represents booking times in UTC and a client-facing local timezone.

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:

| Field | Type | Example |
| - | - | - |
| `bookingStartUtc` | ISO 8601 instant (UTC) | `"2026-06-01T17:00:00.000Z"` |
| `bookingEndUtc` | ISO 8601 instant (UTC) | `"2026-06-01T18:00:00.000Z"` |
| `bookingTz` | IANA timezone identifier | `"America/New_York"` |

And four derived local fields that the server **computes for you**:

| Field | Example | Meaning |
| - | - | - |
| `bookingLocalDate` | `2026-06-01` | The local calendar date the booking starts on. |
| `bookingLocalStartTime` | `13:00` | Local clock time the booking starts. |
| `bookingLocalEndTime` | `14:00` | Local clock time the booking ends. |
| `bookingLocalEndDate` | `2026-06-01` | Local calendar date the booking ends on. |

## 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**:

```
GET /v1/projects/{projectId}/bookings?startDate=2026-06-01T00:00:00Z&endDate=2026-06-02T00:00:00Z
```

`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:

```ts theme={null}
import { fromZonedTime } from 'date-fns-tz';

const tzStart = fromZonedTime('2026-06-01T00:00:00', 'America/New_York');
const tzEnd   = fromZonedTime('2026-06-02T00:00:00', 'America/New_York');
// then pass tzStart.toISOString() / tzEnd.toISOString() as startDate / endDate.
```

> [!NOTE]
>
> 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:

| Field | Meaning |
| - | - |
| `timeSlotStartUtc` | The slot start in UTC, always `Z`-suffixed. Use it as `bookingStartUtc` when you book. |
| `timeSlotDateAndTime` | The same instant as a local clock in the response `timezone`, with that zone's offset **at that instant**. For display. |

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](https://docs.gomarketbox.com/resources/availability.md#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.

| Endpoint | Field |
| - | - |
| `POST …/availability/search`, `…/suppliers`, `…/package-slate`, `…/package-options` | `timezone` |
| `POST …/bookings`, `PATCH …/bookings/{bookingId}` | `bookingTz` |
| `POST …/holds` | `intervals[].bookingTz` |
| `POST …/orders/{orderId}/package-bookings` | `bookingTz` |
| `POST …/suppliers`, `PUT …/suppliers/{supplierId}` | `timezone` |

The error envelope names the field in its message:

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "bookingTz: Must be an IANA timezone identifier such as America/Toronto (abbreviations like EST are not accepted)",
  "statusCode": 400,
  "requestId": "e21d9f4a-6b8c-4e3d-a175-2c9f6b0d8a53"
}
```

Use the canonical zone name — `America/New_York`, not `EST`;
`Europe/London`, not `BST`. Values already stored are not re-validated on
read.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.