Builder API - Dates and Times

Time Zones

Dates and times passed to the Builder API need to be in the time zone set on the project - they cannot be provided in UTC. This to avoid issues with time zone rule changes. See Storing UTC is not a Silver Bullet for a article detailing the problems with time zones and storing future dates in UTC.

Builder APIs can return date times in the project time zone or in UTC. UTC is used for when something happened (e.g. when a discount was created) as these are always in the past.

Date Time

UTC date times returned by the Builder APIs are always in the ISO 8601 format (e.g. 2022-07-08T08:43:08Z).

Local date times are in the same format, but with no offset or time zone (e.g. 2022-07-08T08:43:08)

Seconds and fractions of second (e.g. 2022-07-18T16:42:48.0000000 are optional).

Example - Passing Date Times in Expression

Below is an example of passing a start and end date time for a discount.

{
  "name": "Discount with Start and End Dates",
  "start": "2023-07-01T06:00",
  "end": "2023-07-01T23:59"
}

If the project has a time zone set of Europe/London, the discount will fire after 6am in London which is 5am UTC because London is in British Summer Time.

Example - Receiving Date Times from Discounts API

Below is an example of a discount with start and end dates which are in the time zone on the project created and last modified dates which are in UTC.

{
  "discounts": [
    {
      "id": "5bc3d9e9-5767-4702-94e8-1e515d24b6ad",
      "name": "Discount with Start and End Dates",
      "start": "2023-07-01T06:00:00",
      "end": "2023-07-01T23:59:00",
      "status": "Staged",
      "priority": 5,
      "createdUtc": "2023-04-26T14:43:48.935095Z",
      "createdBy": "UserName",
      "lastModifiedUtc": "2023-04-26T14:43:48.935095Z",
      "lastModifiedBy": "UserName",
      "tags": []
    }
  ]
}

Date

Dates are always in the format YYYY-MM-DD (4 digit year, 2 digit month, 2 digit day of month).

Time

Times are in the format hh:mm (2 digit 24 clock hour, 2 digit minute) or hh:mm:ss (2 digit 24 clock hour, 2 digit minute, 2 digit second).

Example Date Time Handling in JavaScript

Below are some examples of how to handle local and UTC date times returned from the Builder API in JavaScript using the luxon JS library.

Parse Local Time

E.g. you want to use this local date time in the project time zone (in this example Singapore)

luxon.DateTime.fromISO("2022-07-01T17:39:57.000", {zone: 'Asia/Singapore'});

Parse UTC, setting the time zone to London

E.g. you want to use this UTC date time in the project time zone (in this example Singapore)

luxon.DateTime.fromISO("2022-07-05T15:43:36.861777Z", {zone: 'Asia/Singapore'});

Formatting Date Time with no time zone info

dateTime.toFormat("yyyy-MM-dd'T'HH:mm:ss");