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

# Dates and time zones

> How Zenamu represents dates, times, and studio time zones.

## Date-only fields

Balance expiries, birthdays, and registration dates use ISO 8601 calendar dates:

```txt theme={null}
2026-03-15
```

No time, no offset. `validTo`, `validToDate`, `clientBirthday`,
`registrationDate`, and `lastBookingCompletedDate` all use this format.

## Query ranges

The schedule endpoints require `dateFrom` and `dateTo`, both `YYYY-MM-DD` and
both inclusive:

```bash theme={null}
?dateFrom=2026-03-01&dateTo=2026-03-31
```

They are read **in the studio's own time zone**, not in UTC and not in yours.
`dateTo=2026-03-31` covers that whole day up to local midnight, so a 22:00 class
in Prague is included even though it is 21:00 UTC.

Both values must be real calendar dates, and `dateFrom` must be on or before
`dateTo`. A malformed or impossible date returns `400`.

The range is required, and it may span at most **366 days**, counting both ends.
A wider range returns `400`. Together these stop a single call from loading a
studio's entire history — fetch a long period as a few sequential calls.

## Event times

Every class and workshop reports its start and end **three ways**, so you never
have to reconstruct a time zone yourself.

| Field                            | Format                      | Use it for                              |
| -------------------------------- | --------------------------- | --------------------------------------- |
| `start`, `end`                   | `2026-03-15T08:00:00Z`      | Storage, sorting, comparisons           |
| `localTimeStart`, `localTimeEnd` | `2026-03-15T09:00:00+01:00` | Inspect the studio-local representation |
| `timezone`                       | `Europe/Prague`             | Your own formatting and DST math        |

`start` and `end` are always UTC with a `Z` suffix. `localTimeStart` and
`localTimeEnd` are the same instants in the studio's zone, always with a numeric
offset — `+00:00` rather than `Z`, even for a UTC studio.

<Tip>
  For display, format `start` with the IANA `timezone`. Do not parse
  `localTimeStart` and then format it in the visitor's time zone. A studio in
  Prague announces a class at 09:00 regardless of where the visitor is.
</Tip>

`timezone` is an IANA identifier. A studio that never set one reports `UTC`.

## Grant validity

When granting credits or entry passes you do not send an expiry date. You send a
duration, and Zenamu computes the expiry from the moment of the grant:

```json theme={null}
{ "count": 10, "validityTimeValue": 3, "validityTimeUnit": "month" }
```

`validityTimeUnit` is `day`, `week`, `month`, or `year`. Each unit has a ceiling:

| Unit    | Maximum |
| ------- | ------: |
| `day`   |   36500 |
| `week`  |    5200 |
| `month` |    1200 |
| `year`  |     100 |

Exceeding the ceiling fails validation with `400`. The response returns the
resulting `validTo` as a plain date.