Timestamps

The POS Hub API uses ISO 8601 format for timestamps in all API requests and responses. This ensures a consistent and standardized way to represent date and time across the platform.

Overview

Timestamps are used throughout the POS Hub API to indicate when events occur, when objects are created or modified, and to manage time-based data. By using ISO 8601 format, the API provides a clear and unambiguous representation of date and time, which is essential for accurate data processing and interoperability between different systems.

ISO 8601 Format

Here's various examples of how timestamps are represented in ISO 8601 format:

1. Basic Format: YYYY-MM-DDTHH:mm:ssZ

   • Example: 2023-10-01T12:00:00Z
   • This format includes the date, time, and a 'Z' to indicate that the time is in UTC (Coordinated Universal Time).
   • The T separates the date and time components, and the Z indicates that the time is in UTC.

2. With Timezone Offset: YYYY-MM-DDTHH:mm:ss±hh:mm

   • Example: 2023-10-01T12:00:00+02:00
   • This format includes the date, time, and a timezone offset from UTC.
   • The +02:00 indicates that the time is 2 hours ahead of UTC, note that the offset can also be negative, such as -05:00 for 5 hours behind UTC.

3. Date Only: YYYY-MM-DD

   • Example: 2023-10-01
   • This format represents only the date without a time component.

4. Time Only: HH:mm:ss

   • Example: 12:00:00
   • This format represents only the time without a date component.

How Timestamps are processed

When a timestamp is received by the POS Hub API, it first validates that the timestamp is in a valid ISO 8601 format. If the timestamp is valid, we will parse the timestamp and normalize it to UTC and store the most standardized version of the timestamp in the database. This ensures that all timestamps are stored in a consistent format, regardless of the timezone of the client or server.

For example, If you make an API Call and pass the timestmap in the following format:

{
  "placedOn": "2023-10-01T12:00:00+02:00"
}

The POS Hub API will normalize this timestamp to UTC and the value stored in the database will be:

{
  "placedOn": "2023-10-01T10:00:00Z"
}

This is the exact same time as the original timestamp, but it is now stored in a consistent format that can be easily compared, sorted, and queried across different systems.