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	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/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"
    }
  ]
}'

Java

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();

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/lastmile/service_options", 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/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	Required	Description
id	integer		The ID of the service option.
service_option_reference	string		The reference of the service option.
date	string		The date the service will take place in ISO 8601 format.
handoff_time	string		The ETA for shopper to arrive at store.
window	Window		The time window when the service will take place.
availability	OptionAvailability		The availability of this service option.

OptionAvailability Object

Field	Type	Required	Description
available	boolean		Indicates if this service option is available for the user.
reasons	Array(string)		The reasons for unavailability of a service option. Currently, the reasons are related to the laws governing the sale of alcohol. For example, restrictions on quantity, delivery time, pickup, and matched city and county of stores and customers. The reasons are subject to change without notice.
item_codes	Array(string)		The item codes which caused the option to be unavailable.

Window Object

One of the following:

Field	Type	Required	Description
start_at	string		The start of the delivery window in ISO 8601 format.
end_at	string		The end of the delivery window 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 if delivery will happen as soon as possible. Only true when type is asap.

or

Field	Type	Required	Description
immediate_hour	integer		Indicates the number of hours after order creation that delivery will occur.
type	string		Indicates this is an immediate option. 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": 79,
      "service_option_reference": "ezppZD0-NzksIDp0eXBlPT4iU2NoZWR1bGVkRGVsaXZlcnlPcHRpb24iLCA6d2luZG93PT48SW5zdGFjYXJ0OjpFbnRlcnByaXNlOjpCb2JhOjpDb3JlOjpUeXBlczo6VjE6OlNlcnZpY2VPcHRpb25TY2hlZHVsZWRXaW5kb3c6IGRlc2NyaXB0b3I6ICIiLCBzdGFydF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI1NzYwMCwgbmFub3M6IDA-LCBlbmRfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNjQ4MDAsIG5hbm9zOiAwPj59",
      "date": "2018-02-22",
      "window": {
        "start_at": "2018-02-22T00:00:00Z",
        "end_at": "2018-02-22T02:00:00Z",
        "type": "scheduled",
        "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