Working with Dates

Learn about how Square APIs model date information.

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.

• Durations in RFC 3339 format. For example, prep_time_duration, delivery_window_duration, and courier_pickup_window_duration in the FulfillmentDeliveryDetails type. Examples of RFC 3339 durations are as follows:

  • 2 days, 12 hours, 30 minutes, and 15 seconds: "P2DT12H30M15S"
  • 3 hours and 15 minutes: "PT3H15M"

• Working with Monetary Amounts
• Working with Addresses