Timezones

A timezone in the T-Gate platform represents the time-of-day reference under which a branch operates. Timezones are the basis for resolving branch opening hours, special timings, and any other time-sensitive logic anchored to a specific location.

For more details on the hierarchical structure and how different entities relate to each other, please refer to General → High Level Structure Guides.

Model Attributes

A timezone is rendered through two different shapes depending on where it appears in the API:

• Listing endpoint (GET /partner_portal/v1/timezones) returns the lookup form: id, name, utc_offset.
• Embedded form — when a timezone is nested inside another resource (currently the branch payload) — returns name, utc_offset.

The combined set of attributes a timezone can carry is:

Attribute	Description	Type
id	The unique identifier of that table entity. Returned only by the timezones listing endpoint.	Integer
name	The display name of the timezone (e.g. Arabia Standard Time (AST), Eastern Indonesian Time (WIT)). Globally unique across the platform.	String
utc_offset	The difference between local time and UTC, expressed in seconds. Positive for timezones ahead of UTC, negative for those behind.	Integer

📘

utc_offset Is In Seconds

utc_offset is an integer in seconds, not minutes or hours. Applications consuming this value need to divide by 60 to get minutes (or 3600 to get hours) before applying it to a UTC timestamp.

This is the same offset used by the embedded timezone object on a branch, so any logic that calculates branch-local times from UTC should add utc_offset seconds to the UTC value.

📘

Matching Embedded Timezones Against The Listing

The embedded form (inside a branch) does not carry id. To correlate an embedded timezone with an entry from the listing endpoint, match on name — timezone names are enforced to be globally unique.

🌍

Filtering Timezones By Country

The timezones listing endpoint accepts a country_id filter. Pass it when you want to scope the result set to the timezones associated with a specific country — for example, when populating a timezone dropdown after the user has already selected the country of a new branch.

Without the filter, the endpoint returns every timezone configured on the platform.

🕑

Timezones And Opening Hours

Opening hours stored against a branch are relative to the branch's timezone, not UTC. When a partner application reads opening hours from T-Gate and needs to render them in UTC (or compare them to a UTC now), it must apply the branch timezone's utc_offset to translate between the two.

See the branches documentation for the full opening-hours model.

Relationship With Countries

A timezone can be linked to many countries through the country_timezones join, and a country can in turn carry many timezones. The relationship is many-to-many because a single timezone (such as Asia/Riyadh) can apply to multiple countries, and a country can span multiple timezones.

The timezone payload itself does not embed its list of countries. Applications that need to discover which timezones belong to a country should call the timezones listing endpoint with the relevant country_id filter instead.

Relationship With Branches

Every branch is assigned exactly one timezone, and a timezone can be referenced by many branches. The timezone is embedded inside the branch payload using the lighter shape (name, utc_offset) — see the branches documentation for the full branch model.