Build Basics

Working with Dates

All Square endpoints expect dates and timestamps as strings in UTC (e.g., "2013-01-15T00:00:00Z") or offset from UTC to indicate time zone (e.g., "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 may require 1 of 2 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 timezone, use RFC 3339 format. For example, the begin_time field in a Catalog.SearchCatalogObjects request.

Date ranges
Permalink Get a link to this section

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.