Working with Dates
On this page
All Square endpoints expect dates and timestamps as strings in UTC (such as, "2013-01-15T00:00:00Z") or offset from UTC to indicate time zone (such as, "2013-01-15T00:00:00-08:00" for 8 hours behind UTC). Clients must account for daylight saving time when providing offset dates.
In Connect v1, date and timestamp strings always use ISO 8601 format:
Fields that only require a date value can use
YYYY-MM-DD
notation. For example, "2007-04-05".Fields that only require a time value can use 24-hour notation (
HH:MM:SS
). For example, "14:30:00".Fields that require a data and time value use
YYYY-MM-DDTHH:MM
notation. For example, "2007-04-05T14:30".
In Square APIs, fields might require one of two possible formats depending on how the field is used and whether it represents a date or a timestamp:
Fields that accept a partial date or time definition use ISO 8601 format. For example, the
start_date
field in a DateRange definition.Fields that require a full timestamp definition, including a timezone, use RFC 3339 format. For example, the
begin_time
field in a Catalog.SearchCatalogObjects request.
Date ranges
Endpoints that accept an optional date range with begin_time
and end_time
parameters also accept an optional order parameter, which indicates whether results are returned in chronological (ASC
) or reverse-chronological (DESC
) order:
For chronological ordering,
begin_time
is inclusive andend_time
is exclusive.For reverse-chronological ordering,
begin_time
is exclusive andend_time
is inclusive.