Preview time slots for last mile delivery

POST /v2/fulfillment/service_options/last_mile

Previews possible service options for last mile delivery fulfillments.

Use this endpoint when customers have yet to sign in, register, or start shopping, but you want to give them a preview of the delivery time slots that might be available to them at checkout.

Based on the store location_code and/or the delivery postal_code specified in your request, the returned service_options[] reflect current and anticipated shopper availability.

note

By default, all service_options[] have a window.type of scheduled. To retrieve an eta time slot, set with_eta_options to true. You can also get a priority_eta time slot by setting with_priority_eta_options to true.

These service_options[] are for preview purposes only. Don't select one of their id or service_option_reference values and then use it to reserve a standard or reserve a desired window time slot, respectively. Doing so increases the probability that order creation will fail.

To reduce the chances of that happening, always select an id or service_option_reference returned by a list time slots for last mile delivery request and use it to make a reservation.

For details, see Preview time slots.

Security

Name	In	Description
Authorization	header	The Authorization header with the bearer token acquired during authentication.

Parameters

None.

Request

Field	Type	Required	Description
location_code	string		Location code of the store where the delivery driver picks up the order. Either postal code or location code is required.
postal_code	string		The postal code for delivery. Either postal code or location code is required.
cart_total_cents	integer		The total value of all items for the order in cents.
items_count	integer		The number of different types of items in the order.
earliest_option_start_at	string		The earliest time that an order can be ready for delivery. Only time slots that start after this time are retrieved.
units_count	number		The number of all items, including multiples of an item, in the order.
with_eta_options	boolean		Returns ETA options instead of immediate options when true. For more information, contact your Instacart Representative. Defaults to false.
with_priority_eta_options	boolean		Returns Priority ETA options instead of immediate options when true. For more information, contact your Instacart Representative. Defaults to false.
with_handoff_time	boolean		Indicator whether the handoff time is calculated when fetching service option. Defaults to false.
desired_windows	Array(DesiredWindow)		The desired windows for service options.

DesiredWindow Object

Field	Type	Required	Description
starts_at	string		Start time of the desired window in ISO 8601 format.
ends_at	string		End time of the desired window in ISO 8601 format.

info

You can specify either the customer’s postal_code (recommended) or the store’s location_code as the required field for this request. For the most accurate set of time slots for the delivery address, specify the postal_code. If both fields are specified, the store’s address is used, which might return a different set of time slots.

Request examples

cURL

curl --request POST \
  --url https://connect.instacart.com/v2/fulfillment/service_options/last_mile \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_code": "string",
  "postal_code": "string",
  "cart_total_cents": 1,
  "items_count": 1,
  "earliest_option_start_at": "string",
  "units_count": 1,
  "with_eta_options": true,
  "with_priority_eta_options": true,
  "with_handoff_time": true,
  "desired_windows": [
    {
      "starts_at": "string",
      "ends_at": "string"
    }
  ]
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/service_options/last_mile")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"location_code\": \"string\",\n  \"postal_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"earliest_option_start_at\": \"string\",\n  \"units_count\": 1,\n  \"with_eta_options\": true,\n  \"with_priority_eta_options\": true,\n  \"with_handoff_time\": true,\n  \"desired_windows\": [\n    {\n      \"starts_at\": \"string\",\n      \"ends_at\": \"string\"\n    }\n  ]\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"location_code\": \"string\",\n  \"postal_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"earliest_option_start_at\": \"string\",\n  \"units_count\": 1,\n  \"with_eta_options\": true,\n  \"with_priority_eta_options\": true,\n  \"with_handoff_time\": true,\n  \"desired_windows\": [\n    {\n      \"starts_at\": \"string\",\n      \"ends_at\": \"string\"\n    }\n  ]\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>"
}

conn.request("POST", "/v2/fulfillment/service_options/last_mile", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Go

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/fulfillment/service_options/last_mile"

	payload := strings.NewReader("{\n  \"location_code\": \"string\",\n  \"postal_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"earliest_option_start_at\": \"string\",\n  \"units_count\": 1,\n  \"with_eta_options\": true,\n  \"with_priority_eta_options\": true,\n  \"with_handoff_time\": true,\n  \"desired_windows\": [\n    {\n      \"starts_at\": \"string\",\n      \"ends_at\": \"string\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Accept", "application/json")
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
service_options	Array(ServiceOption)		The returned service options.
flags	Flags		Additional properties of the address.

ServiceOption Object

Field	Type	Required	Description
id	integer		The service option ID.
service_option_reference	string		A unique service option reference that acts as a token you pass in downstream requests to place a hold.
date	string		The date and time the service is scheduled to take place in ISO 8601 format.
handoff_time	string		Indicates in ISO 8601 format when the handoff between the store associate and the Instacart shopper is expected to occur. Only applicable to last mile delivery orders and not supported in Fulfillment API v3.
window	Window		The fulfillment window.
availability	OptionAvailability		Indicates whether the service option is available and, if it's not, provides details about why.

OptionAvailability Object

Field	Type	Required	Description
available	boolean		Indicates whether the service option is available. If false, then it cannot be selected. In this case, reasons and item_codes indicate why the service option isn’t available and which items caused the unavailability.
reasons	Array(string)		If available is false, this field lists the reasons why. Currently, these reasons, which are subject to change without notice, all relate to restrictions on the sale of alcohol. For more information, see Unavailability Reasons.
item_codes	Array(string)		The codes of the items which caused the service option to be unavailable.

Window Object

One of the following:

Field	Type	Required	Description
start_at	string		The delivery window's starting date and time in ISO 8601 format.
end_at	string		The delivery window's ending date and time in ISO 8601 format.
type	string		The type of service option. One of scheduled, eta, or priority_eta. To enable eta or priority_eta, contact your Instacart Connect representative.
asap	boolean		Indicates whether delivery is scheduled to occur as soon as possible.

or

Field	Type	Required	Description
immediate_hour	integer		The number of hours from the time of order creation by which fulfillment is expected to be complete. For example, if immediate_hour is 2 and the order is created at 9:00am, fulfillment should complete by 11:00am.
type	string		Indicates that the service option is immediate. Defaults to immediate.

Flags Object

Field	Type	Required	Description
long_distance_delivery	boolean		Whether a delivery to the address will be a long distance delivery.

Reasons for unavailability of a service option

Reason	Description
Unmatched city and county	The city and county of the store and customer must match.

Response examples

200 Success

200 Service options returned with postal code

{
  "service_options": [
    {
      "id": 374,
      "service_option_reference": "ezppZD0-Mzc0LCA6dHlwZT0-OSwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-21",
      "window": {
        "start_at": "2018-02-22T02:00:00Z",
        "end_at": "2018-02-22T04:00:00Z",
        "type": "scheduled",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 375,
      "service_option_reference": "ezppZD0-Mzc1LCA6dHlwZT0-NCwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-21",
      "window": {
        "immediate_hour": 2,
        "type": "immediate"
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 376,
      "service_option_reference": "ezppZD0-Mzc2LCA6dHlwZT0-NywgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTc3NjI4MTc4MCwgbmFub3M6IDIwNDU1NzAwMD4sIGVuZHNfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE3NzYyODg5ODAsIG5hbm9zOiAyMDQ1NTcwMDA-Pn0=",
      "date": "2026-04-15",
      "window": {
        "start_at": "2026-04-15T19:36:20Z",
        "end_at": "2026-04-15T21:36:20Z",
        "type": "eta",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    }
  ]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Blank postal code	"location_code or postal_code required"	1001	{"key":"base"}
400	Invalid location code	"Specified store is not available for lastmile."	1001	{"key":"location_code"}
400	Invalid postal code for store	"We do not currently support delivery from this store to the selected postal_code."	1001	{"key":"postal_code"}
404	Resource not found	"Resource not found"	4000	Not applicable