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	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	Description
`address_line_1`	string	The first address line.
`address_line_2`	string	The second address line.
`address_type`	string	The type of address, e.g., "residential".
`postal_code`	string	The postal/zip code of the address.

OrderItem Object

Field	Type	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).

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

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

Request examples

cURL
Java
Python
Go

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

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

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"))

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

Response examples

200 Success

200 Service option hold returned

{
  "service_option_hold": {
    "id": 2,
    "expires_at": "2018-02-22T00:10:00Z",
    "service_option": {
      "id": 9,
      "service_option_reference": "ezppZD0-OSwgOnR5cGU9PiJTY2hlZHVsZWREZWxpdmVyeU9wdGlvbiIsIDp3aW5kb3c9PjxJbnN0YWNhcnQ6OkVudGVycHJpc2U6OkJvYmE6OkNvcmU6OlR5cGVzOjpWMTo6U2VydmljZU9wdGlvblNjaGVkdWxlZFdpbmRvdzogZGVzY3JpcHRvcjogIiIsIHN0YXJ0X2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjU3NjAwLCBuYW5vczogMD4sIGVuZF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-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

Security​

Parameters​

Request​

Address Object​

OrderItem Object​

Replacement_items Object​

Item Object​

Request examples​

Response​

ServiceOptionHold Object​

ServiceOption Object​

OptionAvailability Object​

Window Object​

Response examples​

200 Success

4XX Errors

Security

Parameters

Request

Address Object

OrderItem Object

Replacement_items Object

Item Object

Request examples

Response

ServiceOptionHold Object

ServiceOption Object

OptionAvailability Object

Window Object

Response examples