Reserve a previewed time slot

POST /v2/fulfillment/users/{user_id}/service_options/{service_option_id}/reserve/cart

Deprecated

This endpoint has been deprecated. To reserve a time slot, use the reserve a time slot endpoint instead.

note

If you called either Preview time slots for delivery or Preview time slots for pickup and you permitted a customer to select a time slot from the results, call this endpoint at checkout to try to reserve the time slot with the saved service_option_id.

warning

This endpoint does not support retailers who use ETA options.

Tries to reserve a selected previewed time slot for the specified user ID and their list of cart items. If there is still capacity and the cart items are allowed to be fulfilled in the time slot, the time slot is reserved for 10 minutes. Otherwise, your site needs to prompt your customer to select a different delivery time slot or pickup time slot. For more information about time slots, see Service options (time slots).

A user ID can have one reserved time slot at a time. If you send another reservation request for this user, even if it specifies the same time slot, the currently reserved time slot is cancelled before the new reservation request is processed.

After a time slot is reserved, save the service_option_hold_id. You specify this ID when creating an order.

Best practice

To reduce the chance that the reservation expires before you can create an order, send the reservation request near the end of the checkout process.

Security

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

Parameters

Name	In	Type	Required	Description
user_id	path	string		The ID of the user.
service_option_id	path	integer		The ID of the service option.

Request

Field	Type	Required	Description
address	Address		The address for the delivery.
items	Array(OrderItem)		The items for delivery.
location_code	string		The store location code used to look-up cart items.

Address Object

Field	Type	Required	Description
address_line_1	string		The first line of the address, e.g., 123 Main St.
address_line_2	string		The second line of the address, e.g., Apt 4B.
address_type	string		The type of address, e.g., residential.
postal_code	string		The postal or zip code of the address.

OrderItem Object

Field	Type	Required	Description
line_num	string		The item's line number in the order.
count	integer		The count of the item. Must be a non-negative integer. Depending on the item's catalog configuration, either this field or 'weight' is required.
weight	number		For items sold by weight, the numerical weight of the item. Depending on the item's catalog configuration, either this field or 'count' is required. The API interprets this value as whatever unit of measure is defined for the item in the catalog, such as lb or kg. Must be a non-negative number.
special_instructions	string		Any special instructions about the item selection.
replacement_policy	string		One of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
metadata	Hash		The item-level metadata.
replacement_items	Array(Replacement_items)		A list of requested replacement items if the original item could not be found. This field needs to be turned on via configuration. Contact your Instacart Connect representative.
item	Item		The item's code.

Replacement_items Object

One of the following:

Field	Type	Required	Description
upc	string		The item's universal product code (upc).

or

Field	Type	Required	Description
rrc	string		The item's retailer reference code (rrc).

Item Object

One of the following:

Field	Type	Required	Description
upc	string		The item's universal product code (upc).

or

Field	Type	Required	Description
rrc	string		The item's retailer reference code (rrc).

Request examples

cURL

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/service_options/{service_option_id}/reserve/cart' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "address": {
    "address_line_1": "string",
    "address_line_2": "string",
    "address_type": "string",
    "postal_code": "string"
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ],
  "location_code": "string"
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/users/{user_id}/service_options/{service_option_id}/reserve/cart")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"address\": {\n    \"address_line_1\": \"string\",\n    \"address_line_2\": \"string\",\n    \"address_type\": \"string\",\n    \"postal_code\": \"string\"\n  },\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"count\": 1,\n      \"weight\": 1,\n      \"special_instructions\": \"string\",\n      \"replacement_policy\": \"no_replacements\",\n      \"metadata\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\"\n      },\n      \"replacement_items\": [\n        {\n          \"upc\": \"string\"\n        }\n      ],\n      \"item\": {\n        \"upc\": \"string\"\n      }\n    }\n  ],\n  \"location_code\": \"string\"\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"address\": {\n    \"address_line_1\": \"string\",\n    \"address_line_2\": \"string\",\n    \"address_type\": \"string\",\n    \"postal_code\": \"string\"\n  },\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"count\": 1,\n      \"weight\": 1,\n      \"special_instructions\": \"string\",\n      \"replacement_policy\": \"no_replacements\",\n      \"metadata\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\"\n      },\n      \"replacement_items\": [\n        {\n          \"upc\": \"string\"\n        }\n      ],\n      \"item\": {\n        \"upc\": \"string\"\n      }\n    }\n  ],\n  \"location_code\": \"string\"\n}"

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

conn.request("POST", "/v2/fulfillment/users/{user_id}/service_options/{service_option_id}/reserve/cart", 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/users/{user_id}/service_options/{service_option_id}/reserve/cart"

	payload := strings.NewReader("{\n  \"address\": {\n    \"address_line_1\": \"string\",\n    \"address_line_2\": \"string\",\n    \"address_type\": \"string\",\n    \"postal_code\": \"string\"\n  },\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"count\": 1,\n      \"weight\": 1,\n      \"special_instructions\": \"string\",\n      \"replacement_policy\": \"no_replacements\",\n      \"metadata\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\"\n      },\n      \"replacement_items\": [\n        {\n          \"upc\": \"string\"\n        }\n      ],\n      \"item\": {\n        \"upc\": \"string\"\n      }\n    }\n  ],\n  \"location_code\": \"string\"\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_option_hold	ServiceOptionHold		The created service option hold.

ServiceOptionHold Object

Field	Type	Required	Description
id	integer		The ID of the service option hold.
expires_at	string		The expiration time of the service option hold in ISO 8601 format.
service_option	ServiceOption		The held service option.

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.

Response examples

200 Success

200 Service option hold returned

{
  "service_option_hold": {
    "id": 2,
    "expires_at": "2018-02-22T00:10:00Z",
    "service_option": {
      "id": 4,
      "service_option_reference": "ezppZD0-NCwgOnR5cGU9PiJTY2hlZHVsZWREZWxpdmVyeU9wdGlvbiIsIDp3aW5kb3c9PjxJbnN0YWNhcnQ6OkVudGVycHJpc2U6OkJvYmE6OkNvcmU6OlR5cGVzOjpWMTo6U2VydmljZU9wdGlvblNjaGVkdWxlZFdpbmRvdzogZGVzY3JpcHRvcjogIiIsIHN0YXJ0X2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjU3NjAwLCBuYW5vczogMD4sIGVuZF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-Pn0=",
      "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	User Not Found	"User Not Found"	1001	{"key":"user_id"}
400	Invalid location code	"Could not find specified store."	1001	{"key":"location_code"}
400	No stores found	"No store location found for given address."	1001	{"key":"address_line_1"}
400	Retry later	"Please try again in a little while"	2003	Not applicable
400	Attempting to reserve an unavailable service option	"Service option is incompatible with the provided parameters."	1001	{"key":"service_option_id"}
400	Blank service option id	"can't be blank"	1001	{"key":"service_option_id"}
403	Inactive user	"User Not Active"	null	Not applicable
404	Resource not found	"Resource not found"	4000	Not applicable