Date conversion and timezones

Overview

Each organisation has a timezone setting that has a significant impact on how dates are handled on the Root platform. When making requests to the Root platform's API, developers should always consider the organisation's timezone and how it affects date handling on the platform.

Standard (non-configurable) endpoints

When making requests to the Root platform's standard (non-configurable) endpoints, any dates included in the request will be converted to ISO 8601 date-time format and converted to UTC.

If the timezone offset is not explicitly included in the date input, the timezone offset is assumed to be the organisation's timezone before being converted to UTC. If the timezone offset is explicitly included in the date input, the supplied timezone offset is used instead of the organisation's timezone.

📘

Date conversion example

For an organisation with a timezone of Africa/Johannesburg the timezone offset is UTC+2.
Date inputs will be converted as follows:

API request body

{
  "date_without_offset": "2022-12-15",
  "date_with_offset": "2022-12-15T00:00:00-05:00"
}

API response body

{
  "date_without_offset": "2022-12-14T22:00:00Z",
  "date_with_offset": "2022-12-15T05:00:00Z"
}

Configurable endpoints

For configurable endpoints, how the date is converted is configured in the validation hooks in the product module code using the joi library. Please refer to the validation and dates section in the product module code guide to find the tools you can use to convert dates for configurable endpoints like the quote endpoint, configured in the quote hook.