Dates and timestamps

All Toast APIs use ISO 8601 string representation for dates and timestamps and all such dates and timestamps are in UTC. Clients must convert dates and times to the appropriate time zone, often the restaurant time zone.

Timestamp formats

Timestamps may be absolute or relative to the implied day. Milliseconds are optional.

The absolute timestamp format is:

yyyy-MM-dd’T’HH:mm:ss.SSSZ

The relative timestamp format is:

HH:mm:ss-hh:mm

When you include an ISO 8601 date in an endpoint URL query parameter, you must URL encode the special characters "+" and "-" signs in the date format.

For example, the "+" in the date 2020-01-01T14:13:12.000+0400 must be escaped to 2020-01-01T14:13:12.000%2B0400.

For more information about URL encoding, see the IETF URI standard.

Daylight savings time

If you submit time-based information to the Toast platform, or you interact with time-based configuration, you need to consider daylight savings time when you do your development. Observe state-specific daylight savings practices when doing development related to daylight savings time.

Submitting time-based information

UTC times are not affected by daylight savings time. If you submit data to Toast that includes timestamps, such as the openedDate and promisedDate on an order or the inDate and outDate on a shift, you must accommodate daylight savings time when you determine the timestamps.

For example:

  • Today is Saturday. Daylight savings time begins tomorrow, meaning that the clock jumps from 1:59 AM to 3:00 AM.

    A guest places a scheduled order to be fulfilled at 6:00 PM tomorrow.

    The openedDate and promisedDate should be set to the UTC equivalent of 5:00 PM local time today. Tomorrow, that timestamp will correspond to 6:00 PM local time.

  • Today is Saturday. Daylight savings time ends tomorrow, meaning that the clock jumps from 1:59 AM back to 1:00 AM.

    If a guest places a scheduled order to be fulfilled at 6:00 PM tomorrow.

    The openedDate and promisedDate should be set to the UTC equivalent of 7:00 PM local time today. Tomorrow, this timestamp will correspond to 6:00 PM local time.

Time-based configuration

Certain configuration in the Toast platform is time-based. For example, a restaurant may use a time-based menu, time-based pricing, or a time-based discount to accommodate their happy hour.

Menu availability, time-based prices, and time-based discounts are all configured relative to a restaurant's local time.

When your integration uses this time-based configuration information, you must shift the times as needed when daylight savings time begins and ends.

Using restaurant hours

The closeoutHour JSON value and schedules object in the restaurants API are both relative to the restaurant's local time.

When interacting with these hours, shift them as needed when daylight savings time begins and ends.