Skip to main content

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.

caution

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

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.
service_option_idpathintegerRequiredThe ID of the service option.

Request

FieldTypeRequiredDescription
addressAddressRequiredThe address for the delivery.
itemsArray(OrderItem)RequiredThe items for delivery.
location_codestringOptionalThe store location code used to look-up cart items.

Address Object

FieldTypeRequiredDescription
address_line_1stringRequiredThe first address line.
address_line_2stringOptionalThe second address line.
address_typestringOptionalThe type of address, e.g., "residential".
postal_codestringRequiredThe postal/zip code of the address.

OrderItem Object

FieldTypeRequiredDescription
line_numstringRequiredThe item's line number in the order.
countintegerOptionalThe count of the item. Must be a non-negative integer.
weightnumberOptionalFor items sold by weight, the numerical weight of the item. 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_instructionsstringOptionalAny special instructions about the item selection.
replacement_policystringOptionalOne of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
replacement_itemsArray(Replacement_items)OptionalA 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.
itemItemRequiredThe item's code.

Replacement_items Object

One of the following:

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

Item Object

One of the following:

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

Request examples

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",
"replacement_items": [
{
"upc": "string"
}
],
"item": {
"upc": "string"
}
}
],
"location_code": "string"
}'

Response

FieldTypeRequiredDescription
service_option_holdServiceOptionHoldRequiredThe created service option hold.

ServiceOptionHold Object

FieldTypeRequiredDescription
idintegerRequiredThe ID of the service option hold.
expires_atstringRequiredThe expiration time of the service option hold in ISO 8601 format.
service_optionServiceOptionRequiredThe held service option.

ServiceOption Object

FieldTypeRequiredDescription
idintegerRequiredThe ID of the service option.
service_option_referencestringOptionalThe reference of the service option.
datestringRequiredThe date the service will take place in ISO 8601 format.
handoff_timestringOptionalThe ETA for shopper to arrive at store.
windowWindowRequiredThe time window when the service will take place.
availabilityOptionAvailabilityRequiredThe availability of this service option.

OptionAvailability Object

FieldTypeRequiredDescription
availablebooleanRequiredIndicates if this service option is available for the user.
reasonsArray(string)OptionalThe 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_codesArray(string)OptionalThe item codes which caused the option to be unavailable.

Window Object

One of the following:

FieldTypeRequiredDescription
start_atstringRequiredThe start of the delivery window in ISO 8601 format.
end_atstringRequiredThe end of the delivery window in ISO 8601 format.
typestringRequiredThe type of service option. One of 'scheduled', 'eta' (contact your Instacart Connect representative), or 'asap' (contact your Instacart Connect representative).
asapbooleanOptionalIndicates if delivery will happen as soon as possible. Only true when type is asap.

or

FieldTypeRequiredDescription
immediate_hourintegerRequiredIndicates the number of hours after order creation that delivery will occur.
typestringRequiredIndicates this is an immediate option. Defaults to immediate.

Response examples

200 Success

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