Preview time slots for delivery

POST /v2/fulfillment/service_options/delivery

Lists the available delivery service options for the specified postal code. In this context, service options are time slots. Availability is based on current and anticipated shopper availability for the relevant store and delivery location.

Use this endpoint when you want to display a list of available time slots before a customer logs in or starts shopping. By default, the time slots returned are immediate and scheduled time slots. To get an ETA time slot with the scheduled time slots, set the with_eta_options field to true. For more information about ETAs and the preview scenario, see Service options.

If you permit a potential customer to select a preview time slot, save the service_option_id. When the customer is ready to check out, call Reserve a time slot with the service_option_id.

If you don't permit a potential customer to select a preview time slot, or if you need to prompt the customer to pick a different time slot, call List time slots for delivery at checkout.

Best practice

Order creation might fail because the preview time slot isn't available anymore when the customer checks out. To reduce the chance of order creation failing, call List time slots for delivery to get a list of validated time slots. Save the service_option_id, and then call Reserve a time slot.

Security

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

Parameters

None.

Request

Field	Type	Description
`postal_code`	string	The postal code for delivery.
`cart_total_cents`	integer	The total value of all items for the order in cents.
`items_count`	integer	The number of items in the order.
`with_eta_options`	boolean	Returns ETA options instead of immediate when true. For more information, contact your Instacart Representative. Defaults to false.
`with_priority_eta_options`	boolean	Returns Priority ETA options instead of immediate when true. For more information, contact your Instacart Representative. 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.

Request examples

cURL
Java
Python
Go

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

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/service_options/delivery")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"postal_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"with_eta_options\": true,\n  \"with_priority_eta_options\": 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  \"postal_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"with_eta_options\": true,\n  \"with_priority_eta_options\": 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/delivery", payload, headers)

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

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

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"postal_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"with_eta_options\": true,\n  \"with_priority_eta_options\": 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, _ := ioutil.ReadAll(res.Body)

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

}

Response

Field	Type	Required	Description
`service_options`	Array(ServiceOption)		The returned service options.

ServiceOption Object

Field	Type	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	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	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' (contact your Instacart Connect representative), or 'asap' (contact your Instacart Connect representative).
`asap`	boolean	Indicates if delivery will happen as soon as possible. Only true when type is asap.

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.

Reasons for unavailability of a service option

Reason	Description
`State law restricts amount of {beer/wine/spirits} to {#} fl oz, cart quantity is: {#} fl oz.`	The quantity of this alcohol type exceeds the state law limit.
`Error validating alcohol quantities. Please try again.`	The quantity of alcohol can’t be validated.
`Unmatched city and county`	The city and county of the store and customer must match.
`Cannot deliver alcohol to this postal code`	Instacart can’t deliver alcohol to this postal code.
`State law doesn't allow delivery of alcohol in this window`	Instacart can’t deliver alcohol in this delivery window because of state law.

Response examples

200 Success

200 Service options returned by postal code

{
  "service_options": [
    {
      "id": 15,
      "service_option_reference": "ezppZD0-MTUsIDp0eXBlPT4iU2NoZWR1bGVkRGVsaXZlcnlPcHRpb24iLCA6d2luZG93PT48SW5zdGFjYXJ0OjpFbnRlcnByaXNlOjpCb2JhOjpDb3JlOjpUeXBlczo6VjE6OlNlcnZpY2VPcHRpb25TY2hlZHVsZWRXaW5kb3c6IGRlc2NyaXB0b3I6ICIiLCBzdGFydF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI1NzYwMCwgbmFub3M6IDA-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`	Missing postal code	"can't be blank"	`1001`	`{"key":"postal_code"}`
`404`	Resource not found	"Resource not found"	`4000`	Not applicable

Security​

Parameters​

Request​

DesiredWindow Object​

Request examples​

Response​

ServiceOption Object​

OptionAvailability Object​

Window Object​

Reasons for unavailability of a service option​

Response examples​