ScheduleTimes Resource

Use the ScheduleTimes resource to fetch a schedule’s times for a single day for a location or cart.

Resources:

Schedule AvailableTimes Duration EarliestTime PickupWindow
DeliveryWindow FulfillmentWindow ScheduleDate ScheduleTime  

Schema type

Use schedule-times to reference this resource in the template schema.

Using the schedule-times resource will make the source template render uncacheable. Refer to this guide on how to load uncacheable resources with the template API.

Querying

Filters nullable

  • location_id string

    Location id of schedule to retrieve. If empty, it will retrieve a schedule based on the active cart (otherwise null).

      {
      "filters": {
          "location_id": "LXGG1JK52W3Z8"
      }
  }

  • fulfillment string

    The fulfillment type for the schedule. Only required for location based schedules.

      {
      "filters": {
          "fulfillment": "PICKUP"
      }
  }

    Valid terms:

          - PICKUP
      - DELIVERY

  • square_online_id boolean

    Flag to identify the resource to be fetched using legacy square_online_ids

      {
      "filters": {
          "location_id": "11ee258c8d63597882fa089e019fd17a",
          "square_online_id": true
      }
  }

  • day string

    day represents the day in the store location’s timezone.

    If empty, the EarliestTime will be returned, but AvailableTimes will be empty.

    If set to now, the day will be set based on the current time.

    Otherwise set day to an ISO date string, e.g. 2024-01-25.

  • interval string

    The time interval for the AvailableTimes. Default is 5m.

      {
      "filters": {
          "interval": "5m"
      }
  }

    Valid terms:

          - 5m
      - 10m
      - 15m
      - 30m

Output (Pickup Hours) 

{
 	"__SO_RESOURCE_TYPE__": "schedule", // internally used resource property. do not modify.
	"resource_type": "SCHEDULE_TIMES",
	"is_outside_scheduling_window": false,
	"earliest_time": {
		"time_formatted": "Today at 4:35 PM",
		"time_unix": 1705527300,
		"time": "2024-01-17T21:35:00+00:00",
		"date": "2024-01-17",
		"prep_time_duration": {
			"in_minutes": 30,
			"rfc3339_interval": "PT30M"
		},
		"label": "4:35 PM",
		"is_adjusted_for_capacity_limits": false
	},
	"available_times": {
		"2024-01-20": {
			"times": [
				{
					"time_formatted": "Saturday at 9:00 AM",
					"time_unix": 1705759200,
					"time": "2024-01-20T14:00:00+00:00",
					"prep_time_duration": {
						"in_minutes": 30,
						"rfc3339_interval": "PT30M"
					},
					"label": "9:00 AM"
				},
				{
					"time_formatted": "Saturday at 9:05 AM",
					"time_unix": 1705759500,
					"time": "2024-01-20T14:05:00+00:00",
					"prep_time_duration": {
						"in_minutes": 30,
						"rfc3339_interval": "PT30M"
					},
					"label": "9:05 AM"
				},
				...
			]
		}
	}
}

Output (Delivery Hours) 

{
	"__SO_RESOURCE_TYPE__": "schedule", // internally used resource property. do not modify.
	"resource_type": "SCHEDULE_TIMES",
	"is_outside_scheduling_window": false,
	"earliest_time": {
		"time_formatted": "Today: 4:50 PM - 5:05 PM",
		"time_unix": 1705527300,
		"time": "2024-01-17T21:35:00+00:00",
		"date": "2024-01-17",
		"prep_time_duration": {
			"in_minutes": 30,
			"rfc3339_interval": "PT30M"
		},
		"label": "4:50 PM",
		"is_adjusted_for_capacity_limits": false,
		"delivery_window": {
			"start": {
				"time_formatted": "4:50 PM",
				"time_unix": 1705528200,
				"time": "2024-01-17T21:50:00+00:00"
			},
			"end": {
				"time_formatted": "5:05 PM",
				"time_unix": 1705529100,
				"time": "2024-01-17T22:05:00+00:00"
			}
		}
	},
	"available_times": {
		"2024-01-20": {
			"times": [
				{
					"time_formatted": "Saturday: 9:15 AM - 9:30 AM",
					"time_unix": 1705759200,
					"time": "2024-01-20T14:00:00+00:00",
					"prep_time_duration": {
						"in_minutes": 30,
						"rfc3339_interval": "PT30M"
					},
					"label": "9:15 AM",
					"delivery_window": {
						"start": {
							"time_formatted": "9:15 AM",
							"time_unix": 1705760100,
							"time": "2024-01-20T14:15:00+00:00"
						},
						"end": {
							"time_formatted": "9:30 AM",
							"time_unix": 1705761000,
							"time": "2024-01-20T14:30:00+00:00"
						}
					}
				},
				{
					"time_formatted": "Saturday: 9:20 AM - 9:35 AM",
					"time_unix": 1705759500,
					"time": "2024-01-20T14:05:00+00:00",
					"prep_time_duration": {
						"in_minutes": 30,
						"rfc3339_interval": "PT30M"
					},
					"label": "9:20 AM",
					"delivery_window": {
						"start": {
							"time_formatted": "9:20 AM",
							"time_unix": 1705760400,
							"time": "2024-01-20T14:20:00+00:00"
						},
						"end": {
							"time_formatted": "9:35 AM",
							"time_unix": 1705761300,
							"time": "2024-01-20T14:35:00+00:00"
						}
					}
				},
				...
			]
		}
	}
}

Output (Pickup Window) 

{
	"__SO_RESOURCE_TYPE__": "schedule", // internally used resource property. do not modify.
	"resource_type": "SCHEDULE_TIMES",
	"is_outside_scheduling_window": false,
	"earliest_time": {
		"time_formatted": "Today: 4:40 PM - 11:00 PM",
		"time_unix": 1705527600,
		"time": "2024-01-17T21:40:00+00:00",
		"date": "2024-01-17",
		"prep_time_duration": {
			"in_minutes": 30,
			"rfc3339_interval": "PT30M"
		},
		"label": "4:40 PM",
		"is_adjusted_for_capacity_limits": false,
		"pickup_window": {
			"start": {
				"time_formatted": "4:40 PM",
				"time_unix": 1705527600,
				"time": "2024-01-17T21:40:00+00:00"
			},
			"end": {
				"time_formatted": "11:00 PM",
				"time_unix": 1705550400,
				"time": "2024-01-18T04:00:00+00:00"
			}
		}
	},
	"available_times": {
		"2024-01-20": {
			"times": [
				{
					"time_formatted": "Saturday: 9:00 AM - 5:00 PM",
					"time_unix": 1705759200,
					"time": "2024-01-20T14:00:00+00:00",
					"prep_time_duration": {
						"in_minutes": 30,
						"rfc3339_interval": "PT30M"
					},
					"label": "9:00 AM",
					"pickup_window": {
						"start": {
							"time_formatted": "9:00 AM",
							"time_unix": 1705759200,
							"time": "2024-01-20T14:00:00+00:00"
						},
						"end": {
							"time_formatted": "5:00 PM",
							"time_unix": 1705788000,
							"time": "2024-01-20T22:00:00+00:00"
						}
					}
				}
			]
		}
	}
}

Output (Delivery Window) 

{
	"__SO_RESOURCE_TYPE__": "schedule", // internally used resource property. do not modify.
	"resource_type": "SCHEDULE_TIMES",
	"is_outside_scheduling_window": false,
	"earliest_time": {
		"time_formatted": "Today: 4:45 PM - 11:00 PM",
		"time_unix": 1705527900,
		"time": "2024-01-17T21:45:00+00:00",
		"date": "2024-01-17",
		"prep_time_duration": {
			"in_minutes": 30,
			"rfc3339_interval": "PT30M"
		},
		"label": "4:45 PM",
		"is_adjusted_for_capacity_limits": false,
		"delivery_window": {
			"start": {
				"time_formatted": "4:45 PM",
				"time_unix": 1705527900,
				"time": "2024-01-17T21:45:00+00:00"
			},
			"end": {
				"time_formatted": "11:00 PM",
				"time_unix": 1705550400,
				"time": "2024-01-18T04:00:00+00:00"
			}
		}
	},
	"available_times": {
		"2024-01-20": {
			"times": [
				{
					"time_formatted": "Saturday: 9:00 AM - 5:00 PM",
					"time_unix": 1705759200,
					"time": "2024-01-20T14:00:00+00:00",
					"prep_time_duration": {
						"in_minutes": 30,
						"rfc3339_interval": "PT30M"
					},
					"label": "9:00 AM",
					"delivery_window": {
						"start": {
							"time_formatted": "9:00 AM",
							"time_unix": 1705759200,
							"time": "2024-01-20T14:00:00+00:00"
						},
						"end": {
							"time_formatted": "5:00 PM",
							"time_unix": 1705788000,
							"time": "2024-01-20T22:00:00+00:00"
						}
					}
				}
			]
		}
	}
}

Schedule resources

Schedule

A schedule for a location or cart.

Field Type Description
available_times AvailableTimes Map of YYYY-MM-DD => schedule date-object. The field name is a date using the YYYY-MM-DD format (for example 2023-11-06).
earliest_time EarliestTime Details about the next available window for fulfillment.
is_outside_scheduling_window Boolean Whether or not earliest available time is outside of scheduling.
resource_type String The resource type identifier.

Back to top

AvailableTimes

Field Type Description
YYYY-MM-DD ScheduleDate Fulfillment schedule details on a specific date.

Back to top

Duration

Field Type Description
in_minutes Number Duration in minutes.
rfc3339_interval String Duration in RFC3339 format.

Back to top

EarliestTime

The next available window for a fulfillment. This is always included in any response.

Field Type Description
is_adjusted_for_capacity_limits Boolean Whether or not earliest available time was bumped because of at-capacity periods (i.e. Order Staggering)
label String Prescribed localized time-only label for use in buyer-facing time selectors.
prep_time_duration Duration Details about Prep time duration.
time_formatted String Human-readable label for time. Dependent on fulfillment type.
time_unix Number UNIX timestamp of pickup/delivery time.
time String RFC3339 formatted date-time.
date String RFC3339 date based on the store location’s timezone.
pickup_window PickupWindow Included if using a window for pickup hours.
delivery_window DeliveryWindow Included if the fulfillment is delivery.

Back to top

PickupWindow

Window for pickup hours

Field Type Description
start FulfillmentWindow Start of the window for the pickup hours.
end FulfillmentWindow End of the window for the pickup hours.

Back to top

DeliveryWindow

Window for delivery hours

Field Type Description
start FulfillmentWindow Start of the window for the delivery hours.
end FulfillmentWindow End of the window for the delivery hours.

Back to top

FulfillmentWindow

Window for fulfillment hours

Field Type Description
time_formatted String Human-readable label for time.
time_unix Number UNIX timestamp of pickup/delivery time.
time String RFC3339 formatted date-time.

Back to top

ScheduleDate

Schedule date details.

Field Type Description
times ScheduleTime[] The available times for the schedule date

ScheduleTime

Schedule time details.

Field Type Description
label String Prescribed localized time-only label for use in buyer-facing time selectors.
prep_time_duration Duration Details about Prep time duration.
time_formatted String Human-readable label for time. Dependent on fulfillment type.
time_unix Number UNIX timestamp of pickup/delivery time.
time String RFC3339 formatted date-time.
pickup_window PickupWindow Included if using a window for pickup hours.
delivery_window DeliveryWindow Included if the fulfillment is delivery.