Working with Dates

General guidance

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.

Connect v1

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".

Square APIs

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 and end_time is exclusive.

• For reverse-chronological ordering, begin_time is exclusive and end_time is inclusive.