Date and Time Format

Overview

Fields in the Remote API will frequently make use of Date and Time values. However, everyone writes dates and times differently. To ensure all dates and times are represented unambiguously, we use the ISO8601 Date and Time Format in the Remote API, both for parameters you provide to us, and the responses we provide to you.

Anatomy of the ISO8601 Date and Time Format

The ISO8601 date and time format consists of two components: The date component and the time component. Here’s an example of a date and time value represented in ISO8601 format:

The date and time components are always separated by the letter T. The time zone identifier, Z stands for “Zulu”, which is another way of saying “this time is in UTC” or “the time zone offset of this component is 00:00”.

ℹ️ The Remote API documentation will always accept date and time values with the Z time zone identifier. Unless specified otherwise in the API documentation, replacing the time zone identifier with the time offset (such as -05:00 or +08:00) may lead to unexpected behavior. Therefore, we recommend you use Z as the time zone identifier when providing date and time values.

We can represent the date and time example above with a more generic format, which is generally what you will see in our documentation:

Providing Only Date or Only Time Values

Some Remote API parameters will only require date or time values. In this case, we still follow the ISO8601 format, but you only need to provide one of the components.

For a parameter that only requires date values, you would provide the date component of the ISO8601 format: 2022-07-15 (YYYY-MM-DD)

For a parameter that only requires time values, you would provide the time component of the ISO8601 format: 15:23:46 (HH:MM:DD). You may notice that the timezone identifier is missing; that’s intentional, as time zone values are typically not necessary in this case, since there’s no date provided.