Skip to main content

Desired windows

Desired windows represent requested delivery time periods. You provide Instacart one or more desired time slots and a single delivery location, and then the fulfillment engine checks whether capacity exists to fulfill the order.

If you're integrating with multiple third-party fulfillment providers, desired windows allow you to be more flexible with the time slots that you present to customers. Desired windows must be at least 60 minutes long and they should start and end on the hour.

Except for pickups, you can use desired windows in all of Instacart’s supported fulfillment models. But how you use them depends on the model.

How desired windows work in dispatch last mile deliveries​

In dispatch last mile deliveries (Dispatch LMD), you display time slots to customers that haven’t yet been confirmed by Instacart but are during periods of the day that typically have significant delivery capacity. You then pass the start and end time of the customer’s selected window in the order creation request. After that, Instacart either schedules delivery for the requested window or, if capacity doesn’t exist, finds the best alternative.

The following is a high level outline of a Dispatch LMD implementation that uses desired windows:

  1. After customers have filled their cart, initiated checkout, and provided their address information, you display one or more delivery time slots for them to select from. These time slots haven’t yet been validated by Instacart, so they should encompass periods when delivery capacity is typically high.
  2. Customers select a time slot and complete checkout.
  3. In the create dispatch LMD order request, you assign their selection to start_at and end_at and set fallback_to_soonest_sameday to true.
  4. Instacart checks whether there’s delivery capacity during your requested time slot. If capacity exists, the fulfillment engine schedules delivery for that window. If it doesn’t, it selects the earliest alternative on that same day.
  5. In either case, if Instacart successfully validates the order, you receive the brand new callback, which contains the scheduled delivery_window.

How desired windows work in deliveries and last mile deliveries​

In deliveries and last mile deliveries (LMD), you specify a delivery address and your desired windows when requesting service options. Instacart then checks whether capacity exists to fulfill the order during those time periods.

The following is a high level outline of a deliveries implementation with desired windows:

note

An LMD implementation has a similar flow.

  1. After customers have filled their cart, initiated checkout, and provided their address information, decide which delivery windows you want to present to them. For example, you might decide to let your customers select from blocks of time that are one, two, or three hours long.
  2. In a get service options request, specify the starts_at and ends_at date-time values of these desired_windows[].
  3. For each of your requested windows, Instacart determines whether delivery capacity exists, and, if it does, returns a corresponding service_options[] which has a window with a start_at and end_at date-time.
  4. In human readable form, present these windows to customers and prompt them to make a selection.
  5. After they make their choice, pass the selected option’s service_option_reference in the body of a reserve a time slot for a desired window request and then save the returned id and expires_at of the service_option_hold.
  6. After customers provide payment and complete checkout, and ideally before the hold expires, assign its identifier to service_option_hold_id in the body of a create delivery order request.
  7. If Instacart successfully validates the order, you receive the brand new callback, which contains the scheduled delivery_window.

Requests that accept desired windows​

In the create dispatch LMD order request, you specify a single desired window by defining a start_at and end_at date-time.

In the following requests, you define one or more desired_windows[], each with a starts_at and ends_at date-time:

Last updated on