Working with Dates

Learn about how Square APIs model date and time information.

Link to section

Overview

Square APIs use standardized string formats based on ISO 8601 and RFC 3339 to represent dates, timestamps, and durations. This consistent approach ensures reliable date/time handling across platforms and time zones.

Date and time fields in Square APIs are always provided as strings, even when representing numeric values like durations. For specific format requirements, always check the documentation for the API endpoint you're using.

Link to section

Quick reference

TypeFormatExample
DateYYYY-MM-DD"2023-05-01"
UTC timestampYYYY-MM-DDTHH:MM:SSZ"2025-01-15T00:00:00Z"
Timestamp with offsetYYYY-MM-DDTHH:MM:SS±hh:mm"2025-01-15T00:00:00-08:00"
Duration (full)P[n]Y[n]M[n]DT[n]H[n]M[n]S"P1Y2M3DT12H30M15S"
(1 year, 2 months, 3 days, 12 hours, 30 minutes, 15 seconds)
Duration (time only)PT[n]H[n]M[n]S"PT3H15M"
(3 hours and 15 minutes)
Link to section

Date format

Square APIs use the ISO 8601 format (YYYY-MM-DD) to represent a calendar day without time information. This format is used in fields such as:

Link to section

Example

Field typeFormatExample
DateYYYY-MM-DD"2023-05-01"
Link to section

Timestamp format

Timestamps include date and time and follow the RFC 3339 format. For example, this format is used in fields such as:

Timestamps can be represented as:

  • UTC time using the YYYY-MM-DDTHH:MM:SSZ format.
  • Offset time to specify a time zone using YYYY-MM-DDTHH:MM:SS±hh:mm (such as -08:00 for 8 hours behind UTC).
Link to section

Examples

Field typeFormatExample
UTC timestampYYYY-MM-DDTHH:MM:SSZ"2013-01-15T00:00:00Z"
Timestamp with offsetYYYY-MM-DDTHH:MM:SS±hh:mm"2013-01-15T00:00:00-08:00"

Note

  • Z at the end of a timestamp indicates UTC time (Zulu).
  • If you're using offset timestamps, check the documentation to ensure whether adjustments are made for Daylight Savings Time (DST).
Link to section

Duration format

Durations represent a length of time rather than a specific date or time. They follow the ISO 8601 duration format as defined by ISO 8601 and clarified in RFC 3339.

These durations are used in fields such as:

Durations are expressed as a string starting with "P" (for period) and using specific time units:

  • Y for years
  • M for months
  • D for days
  • T to separate the date and time components
  • H for hours
  • M for minutes (when appearing after "T")
  • S for seconds

Warning

Don't confuse the "M" for months with the "M" for minutes. Minutes follow a "T" or "H" time unit. For example, "P5M" is five months and "PT5M" is five minutes.

Note

Alternatively, durations can be expressed in weeks using "W", such as "P4W" for 4 weeks. Week-based durations are supported in some endpoints, particularly in fulfillment-related fields. For example:

  • pickup_window_duration: "P1W3D" (1 week and 3 days)
  • delivery_window_duration: "P2W" (2 weeks)

The week format cannot be combined with other units (for example, "P1W2D" isn't allowed).

Link to section

Example

Duration typeFormatExample
Full duration (date and time)P[n]Y[n]M[n]DT[n]H[n]M[n]S"P1Y2M3DT12H30M15S" (1 year, 2 months, 3 days, 12 hours, 30 minutes, 15 seconds)
Time-only durationPT[n]H[n]M[n]S"PT3H15M" (3 hours and 15 minutes)
Weeks-only durationP[n]W"P4W" (4 weeks)
Link to section

See also