List time slots for last mile delivery

POST /v2/fulfillment/lastmile/service_options

Deprecated

This endpoint has been replaced by List time slots for last mile delivery and Preview time slots for last mile delivery. The new URIs are consistent in format with the delivery and pickup workflows. This change reflects our commitment to making our API more intuitive to use when implementing multiple fulfillment workflows in your e-commerce site. The deprecated endpoint is still supported for existing implementations. For new implementations, optionally use Preview time slots for last mile delivery to display time slots before a shopper begins shopping. Use List time slots for last mile delivery to retrieve time slots that are available when the customer is checking out.

Lists the available delivery service options for the customer's location. In this context, service options are time slots, such as Today 4pm-6pm or Friday 9am-11am. Availability is based on current and anticipated shopper availability for the relevant store and delivery location. The list includes immediate and scheduled time slots.

After a time slot is selected, save the service_option_id. You specify the ID when reserving the time slot.

Security

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

Request

Field	Type	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
Java
Python
Go

curl --request POST \
  --url https://connect.instacart.com/v2/fulfillment/lastmile/service_options \
  --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"
    }
  ]
}'

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/lastmile/service_options")
  .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();

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/lastmile/service_options", payload, headers)

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

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

package main

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

func main() {

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

	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	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	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	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.

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.

Response examples

200 Success

200 Service options returned

{
  "service_options": [
    {
      "id": 398,
      "service_option_reference": "ezppZD0-Mzk4LCA6dHlwZT0-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": 399,
      "service_option_reference": "ezppZD0-Mzk5LCA6dHlwZT0-NCwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-21",
      "window": {
        "immediate_hour": 2,
        "type": "immediate"
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 400,
      "service_option_reference": "ezppZD0-NDAwLCA6dHlwZT0-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

Security​

Request​

DesiredWindow Object​

Request examples​

Response​

ServiceOption Object​

OptionAvailability Object​

Window Object​

Flags Object​

Response examples​