Dates and Timezones

💡 Technical representation of dates in the Billy API

The Billy API exposes two types of dates depending on their context:

User Action Dates (UTC)

Dates corresponding to user actions are always stored and returned in UTC (Coordinated Universal Time) in ISO 8601 format.

These dates include:

• Ticket purchase (issuedAt): exact date and time of purchase
• Ticket cancellation (cancelledAt): date and time of cancellation
• Event creation (createdAt)
• Last modification (updatedAt)
• …

These UTC timestamps ensure precise and consistent action tracking, regardless of the user's or event's timezone.

Event-Related Dates (Local Timezone)

Dates related to the event schedule are expressed in the event's timezone (eventTimezone).

These dates include:

• Session date (startAt): session start time in the event's local timezone

Example

An event in Paris with a session at 8:30 PM:

{
  "eventTimezone": "Europe/Paris",
  "sessions": [
    {
      "startAt": "2025-03-21T20:30:00.000+01:00",
      "durationMinutes": 180
    }
  ]
}

ISO 8601 Date Format

The Billy API uses the ISO 8601 format:

YYYY-MM-DDTHH:mm:ss.uuuuu+00:00

Examples

{
  "createdAt": "2025-01-15T10:42:31.00000+00:00",
  "updatedAt": "2025-01-20T09:12:05.00000+00:00",
  "startAt": "2025-03-21T19:30:00.00000+00:00"
}

Format Components

The eventTimezone Field

Each event has an eventTimezone field indicating the event's timezone in IANA format (e.g., Europe/Paris, America/New_York).

Supported Timezone List

The Billy API supports all timezones in IANA format. Here are some common examples:

For the complete list, see the IANA database.