Learn about how Square APIs model date and time information.
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.
| Type | Format | Example |
|---|---|---|
| Date | YYYY-MM-DD | "2023-05-01" |
| UTC timestamp | YYYY-MM-DDTHH:MM:SSZ | "2025-01-15T00:00:00Z" |
| Timestamp with offset | YYYY-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) |
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:
start_dateandend_datein a DateRange object.arrival_datein a Payout object.birthdayin a Customer object.
| Field type | Format | Example |
|---|---|---|
| Date | YYYY-MM-DD | "2023-05-01" |
Timestamps include date and time and follow the RFC 3339 format. For example, this format is used in fields such as:
created_atandupdated_atin an Order object.paired_atin a DeviceCode object.effective_atin a PayoutEntry object.
Timestamps can be represented as:
- UTC time using the
YYYY-MM-DDTHH:MM:SSZformat. - Offset time to specify a time zone using
YYYY-MM-DDTHH:MM:SS±hh:mm(such as-08:00for 8 hours behind UTC).
| Field type | Format | Example |
|---|---|---|
| UTC timestamp | YYYY-MM-DDTHH:MM:SSZ | "2013-01-15T00:00:00Z" |
| Timestamp with offset | YYYY-MM-DDTHH:MM:SS±hh:mm | "2013-01-15T00:00:00-08:00" |
Note
Zat 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).
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:
prep_time_durationin a Fulfillment object.expected_durationin a BreakType object.delay_durationin a Payment object.
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).
| Duration type | Format | Example |
|---|---|---|
| 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 duration | PT[n]H[n]M[n]S | "PT3H15M" (3 hours and 15 minutes) |
| Weeks-only duration | P[n]W | "P4W" (4 weeks) |