Preview time slots for pickup

POST /v2/fulfillment/service_options/pickup

Previews possible service options for pickup 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 pickup time slots that might be available to them at checkout.

Based on the store location_code 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 pickup 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.

Request

Field	Type	Description
`location_code`	string	The location code of the store fulfilling the order.
`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.

Request examples

cURL
Java
Python
Go

curl --request POST \
  --url https://connect.instacart.com/v2/fulfillment/service_options/pickup \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_code": "string",
  "cart_total_cents": 1,
  "items_count": 1,
  "with_eta_options": true
}'

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/service_options/pickup")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"location_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"with_eta_options\": true\n}")
  .asString();

import http.client

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

payload = "{\n  \"location_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"with_eta_options\": true\n}"

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

conn.request("POST", "/v2/fulfillment/service_options/pickup", 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/service_options/pickup"

	payload := strings.NewReader("{\n  \"location_code\": \"string\",\n  \"cart_total_cents\": 1,\n  \"items_count\": 1,\n  \"with_eta_options\": true\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 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', 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.

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.

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.
`Unfortunately alcohol pickup is not available at this location. Please remove alcohol from your basket or try delivery.`	Alcohol pickup is not available at this location.

Response examples

200 Success

200 Service options returned by location code

{
  "service_options": [
    {
      "id": 19,
      "service_option_reference": "ezppZD0-MTksIDp0eXBlPT4iUGlja3VwT3B0aW9uIiwgOndpbmRvdz0-PEluc3RhY2FydDo6RW50ZXJwcmlzZTo6Qm9iYTo6Q29yZTo6VHlwZXM6OlYxOjpTZXJ2aWNlT3B0aW9uU2NoZWR1bGVkV2luZG93OiBkZXNjcmlwdG9yOiAiIiwgc3RhcnRfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNTc2MDAsIG5hbm9zOiAwPiwgZW5kX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjY0ODAwLCBuYW5vczogMD4-fQ==",
      "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": []
      }
    },
    {
      "id": 20,
      "service_option_reference": "ezppZD0-MjAsIDp0eXBlPT4iUGlja3VwRXRhT3B0aW9uIiwgOndpbmRvdz0-PEluc3RhY2FydDo6RW50ZXJwcmlzZTo6Qm9iYTo6Q29yZTo6VHlwZXM6OlYxOjpTZXJ2aWNlT3B0aW9uU2NoZWR1bGVkV2luZG93OiBkZXNjcmlwdG9yOiAiIiwgZW5kX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjY0ODAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-22",
      "window": {
        "start_at": "2018-02-22T00:00:00Z",
        "end_at": "2018-02-22T02:00:00Z",
        "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`	Invalid location code	"Specified store is not available for pickup."	`1001`	`{"key":"location_code"}`
`404`	Resource not found	"Resource not found"	`4000`	Not applicable

Security​

Request​

Request examples​

Response​

ServiceOption Object​

OptionAvailability Object​

Window Object​

Flags Object​

Reasons for unavailability of a service option​

Response examples​