Timezone Handling¶

The Partner API provides flexible timezone handling through the optional X-Client-Timezone HTTP header. This allows partners to receive dates and times in their users' local timezone without client-side conversion.

Overview¶

By default, all dates and times in API responses are returned in UTC using ISO 8601 format. Partners can optionally request localized times by including the X-Client-Timezone header with a valid IANA timezone identifier.

Request Header¶

The header accepts two formats:

1. IANA timezone identifiers (e.g., America/New_York) - DST-aware; automatically adjusts between standard and daylight time based on the date
2. Timezone abbreviations (e.g., EST, PDT) - Fixed offset; always uses the same UTC offset regardless of date

This distinction allows you to choose whether you want automatic DST handling or explicit control over the offset.

Response Behavior¶

Timestamp Format¶

All timestamps are returned in ISO 8601 format:

• UTC (default): Uses the Z suffix notation (e.g., 2024-01-15T19:30:00Z)
• With timezone: Includes the UTC offset (e.g., 2024-01-15T14:30:00-05:00)

Examples¶

Example 1: No Header (Default UTC)¶

Request:

GET /api/partner/v1/meetings/mtg_abc123
Authorization: Bearer <token>

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "mtg_abc123",
  "title": "Project Sync",
  "scheduled_start": "2024-01-15T19:30:00Z",
  "scheduled_end": "2024-01-15T20:30:00Z",
  "created_at": "2024-01-10T14:22:00Z"
}

No X-Client-Timezone response header is included.

Example 2: Valid Timezone¶

Request:

GET /api/partner/v1/meetings/mtg_abc123
Authorization: Bearer <token>
X-Client-Timezone: America/New_York

Response:

HTTP/1.1 200 OK
Content-Type: application/json
X-Client-Timezone: America/New_York

{
  "id": "mtg_abc123",
  "title": "Project Sync",
  "scheduled_start": "2024-01-15T14:30:00-05:00",
  "scheduled_end": "2024-01-15T15:30:00-05:00",
  "created_at": "2024-01-10T09:22:00-05:00"
}

The response header echoes America/New_York, confirming the timezone used.

Example 3: Invalid Timezone (Fallback to UTC)¶

Request:

GET /api/partner/v1/meetings/mtg_abc123
Authorization: Bearer <token>
X-Client-Timezone: Invalid/Timezone

Response:

HTTP/1.1 200 OK
Content-Type: application/json
X-Client-Timezone: UTC

{
  "id": "mtg_abc123",
  "title": "Project Sync",
  "scheduled_start": "2024-01-15T19:30:00Z",
  "scheduled_end": "2024-01-15T20:30:00Z",
  "created_at": "2024-01-10T14:22:00Z"
}

The response header returns UTC, indicating the fallback was applied. No error is returned—the API silently defaults to UTC.

Request Body Timestamps¶

When sending timestamps in request bodies (e.g., creating or updating meetings), you should:

1. Preferred: Send timestamps in UTC with Z suffix
2. Acceptable: Include an explicit offset (e.g., -05:00)

{
  "title": "Team Standup",
  "scheduled_start": "2024-01-20T15:00:00Z",
  "scheduled_end": "2024-01-20T15:30:00Z"
}

The X-Client-Timezone header does not affect how request body timestamps are interpreted—they are always parsed as provided.

Date-Only Fields¶

Fields containing only a date (no time component) are not affected by the timezone header. These are returned as-is in YYYY-MM-DD format.

IANA Identifiers vs Abbreviations¶

Understanding the difference between these two formats is important for handling Daylight Saving Time correctly.

IANA Timezone Identifiers (DST-Aware)¶

IANA identifiers automatically switch between standard and daylight time based on the date:

For a complete list, see the IANA Time Zone Database.

Timezone Abbreviations (Fixed Offset)¶

Abbreviations always use a fixed UTC offset, regardless of the current date. Use these when you need explicit control and don't want automatic DST adjustment:

Choosing Between Formats¶

Best Practices¶

1. Store UTC, display local: Store all timestamps in UTC server-side. Use this header for display purposes only.

2. Use IANA identifiers for user-facing times: They automatically handle DST transitions correctly.

3. Use abbreviations for fixed-offset requirements: When you need a consistent offset regardless of date (e.g., "always show PST for West Coast reports").

4. Validate timezone client-side: Check that the timezone value is valid before sending to avoid unexpected UTC fallback.

5. Cache considerations: If caching API responses, include X-Client-Timezone in your cache key, as the same endpoint returns different values based on this header.

SDK Support¶

The Partner SDK provides helper methods for timezone handling:

import { ContioPartnerClient } from '@contio/partner-sdk';

const client = new ContioPartnerClient({
  // ... other config
  defaultTimezone: 'America/New_York'  // Applied to all requests
});

// Or per-request:
const meeting = await client.meetings.get('mtg_abc123', {
  timezone: 'Europe/London'
});