Timezones

These are the endpoints that are available under the /timezones path, which lists all the different timezones that are available on your business account.

There are no parameters included with timezones calls.

Note: the GET /timezones call returns a full array of 377 timezone objects (for a full list of all the different timezones, look at this page, and for a list of all timezone abbreviations with their UTC offsets, look at this page). We have included one of these in our API response below as an example.

[{
    "sortOrder": 1,
    "timeZoneCode": "US/Eastern",
    "timeZoneDesc": "US/Eastern",
    "timeZoneId": 367,
    "visible": null
}]

Timezones API Interactions with Other APIs

The Timezones API interacts with the Locations, Staff, and Services APIs to ensure that all timezones used for scheduling appointments are synchronized. The timezones objects work together in a fairly complex manner. First we will look at the hierarchy used when determining the times that get displayed for appointments.

If the location group has a timezone assigned to it, then the timezone of that location group will be used to display the list of available times on your web scheduler. The only exception would be if that location's profile had the "Allow Timezone Change" property, which is found found under Settings > Time > Time Panel Settings, set to "Allow Clients to Change Timezone" - in other words, if the allowTZChange property on the location object is equal to 1. If it is, the scheduler would show the times in the timezone of the client booking the appointment. Adding a timezone for a location group is optional - if one is not added, then the timezone used will proceed as described in the next paragraph.

If the location group doesn't have a timezone, but the specified location does, then the timezone of that location will be used to display the list of available times. Again, the only exception would be if the "Allow Timezone Change" dropdown on the location profile is set to "Allow clients to change timezone". The "Allow Timezone Change" dropdown on the location profile could also be set to "Default", in which case it would read from the parent setting, and the allowTZChange property on the location would be set to null. Adding a timezone for a location is also optional - if one is not added, then the timezone used will proceed as described in the next paragraph.

If a location doesn't have a timezone set, then the timezone of the staff will be used to display available times. This frequently happens when a client is booking at a VIRTUAL location where the staff members may be on a different side of the globe than the client, making a time zone conversion necessary. If the "Allow Timezone Change" property is set to "Allow clients to change timezone", and the client selects to book their appointment at a location with no timezone set and with a staff person that has a timezone set, then the appointment times will convert from the staff's timezone to display to the client in that client's own timezone. 

If none of these has a timezone set (location group, location, nor staff), then the timezone of the business will be used. If you want to view the business object, you can click on your username dropdown in the top right of the app and go to "Account Settings". Call is GET /business. This is the only object where the timezone is required as it gets used as the last resort in case all the checks described above fail. The same exception applies, though, if the "Allow Timezone Change" property is set to allow clients to change the timezone, and the times will just convert from the business's timezone to show in the clients timezone. Next we will look at the timeZone and allowTZChange properties on your locations objects and how they get set.

If a location is a physical location - that is, if the locationType property on the location object is set to PHYSICAL - the timezone used by clients would always be the same, so you would set the dropdown to "Do not allow clients to change timezones" - that is, the allowTZChange property on the location object would be set to 0. This is of course assuming that the specified location is only located in one timezone.

If a location is a virtual location - that is, if the locationType property on the location object is set to VIRTUAL - the timezone that gets used by your clients would vary, so you would not have the option to set a timezone on the location profile - that is, the timeZone property on the location object would be set to null. This is because if a client is meeting with a staff member over Skype or another telecommunication app, the client is in one timezone and the staff is in one timezone, but the location of the appointment itself is timezone neutral. You would therefore set the dropdown to "Allow clients to change timezones" - that is, the allowTZChange property on the location object would be set to 1. So when a client goes to book an appointment, if they select the virtual location the scheduler will look at their browser, detect their timezone, and show the staff's availability at the virtual location with the times converted to the client's timezone. 

If a location has its locationType property set to VARIABLE, the timezone should be treated the same as if it were a virtual location. This is because in this case the client would be entering the location address at the time of booking, so once the address gets entered we'd look up the timezone at that point and use that to properly display the suggested timeslots on the scheduler.