Learn about how Square APIs model date information.
Build Basics

Working with Dates

When working with dates, the Square API endpoints expect the following:

  • Dates in ISO 8601 format (YYYY-MM-DD). For example, start_date and end_date in the DateRange type. The ShiftWorkDay.date_range field is of the DateRange type.

  • Timestamps (date and time) in RFC 3339 format. For example, start_at and end_at in the TimeRange type. In the SearchOrders request body, the query.filter.date_time_filter.created_at field is of the TimeRange type. It can be:

    • UTC time "2013-01-15T00:00:00Z".

    • An offset from UTC time to indicate a time zone, such as "2013-01-15T00:00:00-08:00" (for 8 hours behind UTC time).

Clients must account for daylight savings time when providing offset dates.


The Square Connect V1 API is a deprecated API. If you're still using this API, note that 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".

We've made improvements to our docs.
Prefer the old format?