Skip to main content

Timezone Handling

Overview​

Our APIs use different date and time formats depending on the context. Understanding these distinctions is crucial for proper integration, or it may lead to incorrect timezone handling.

1. Catalog​

The Catalog has two API surfaces, with different conventions.

Read APIs: Organization Local Time​

Date-times from the catalog read endpoints (event and performance start times, match start times, timeslot windows, membership validity dates, etc.) are returned in ISO 8601 format with an explicit UTC offset:

YYYY-MM-DDTHH:mm:ss±hh:mm — for example 2022-03-10T12:15:50+01:00

The wall-clock part is the local time of the organization that owns the sales channel, so it reads the way the event is advertised. The offset is always present, so the value is also an unambiguous point in time: you can convert it to any zone without extra context, and you must not assume it is UTC.

Date filters​

The catalog search filters — performanceDateFrom / performanceDateTo on events, matchDateFrom / matchDateTo on competitions, and modifiedAfter on seat queries — are compared as absolute points in time, so the offset is required. A value without one (2026-01-01T00:00:00) is rejected with 400.

Setup APIs: UTC​

The catalog Setup APIs (/s360/v3/setup/**) — the configuration endpoints for performance, match, membership and timeslot times — return their date-times in UTC, ISO 8601 with a Z offset:

YYYY-MM-DDTHH:mm:ssZ

The wall-clock here is UTC, not the organization's local time. The same performance the Read APIs return as 2022-03-10T12:15:50+01:00 is returned as 2022-03-10T11:15:50Z by the Setup APIs. Aligning the Setup APIs with organization local time is planned.

2. Actions: UTC​

All API actions and system events are timestamped in UTC, in ISO 8601 format with a Z offset: YYYY-MM-DDTHH:mm:ssZ (millisecond precision is not guaranteed).

  • File creation and last-modification times
  • Payment date
  • Shipment and collection dates

Examples​

Catalog Read Object (Organization Local Time)​

{
  "performance": {
    "id": "123",
    "name": "Evening Show",
    "startDateTime": "2022-03-10T12:15:50+01:00"
  }
}

Catalog Setup Object (UTC)​

{
  "performance": {
    "id": "123",
    "name": "Evening Show",
    "startDateTime": "2022-03-10T11:15:50Z"
  }
}

Action Object (UTC)​

{
  "file": {
    "id": "file_789",
    "creationDateTime": "2024-01-15T19:30:00Z",
    "state": "CLOSED"
  }
}