Skip to main content

Reserve a previewed time slot

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

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.

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

NameInRequiredDescription
user_idpathโœ…The ID of the user.
service_option_idpathโœ…The ID of the service option.

Request#

FieldTypeRequiredDescription
addressAddressโœ…The address for the delivery.
itemsArray(Items)โœ…The items for delivery.
location_codestringThe store location code used to look-up cart items.

Address Object#

FieldTypeRequiredDescription
address_line_1stringโœ…The first address line.
address_line_2stringThe second address line.
address_typestringThe type of address, e.g., "residential".
postal_codestringโœ…The postal/zip code of the address.

Items Object#

FieldTypeRequiredDescription
line_numstringโœ…The item's line number in the order.
countintegerThe count of the item. Must be a non-negative integer.
weightnumberThe weight of the item (defaults to lbs in the US). Must be a non-negative number.
special_instructionsstringAny special instructions about the item selection.
replacement_policystringOne of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
replacement_itemsArray(Replacement_items)A list of requested replacement items if the original item could not be found.
itemItemโœ…The item's code.

Replacement_items Object#

One of the following:

FieldTypeRequiredDescription
upcstringโœ…The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringโœ…The item's retailer reference code (rrc).

Item Object#

One of the following:

FieldTypeRequiredDescription
upcstringโœ…The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringโœ…The 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_holdService_option_holdโœ…The created service option hold.

Service_option_hold Object#

FieldTypeRequiredDescription
idintegerโœ…The ID of the service option hold.
expires_atstringโœ…The expiration time of the service option hold in ISO 8601 format.
service_optionService_optionโœ…The held service option.

Service_option Object#

FieldTypeRequiredDescription
idintegerโœ…The ID of the service option.
datestringโœ…The date the service will take place in ISO 8601 format.
windowWindowโœ…The time window when the service will take place.
availabilityAvailabilityโœ…The availability of this service option.

Availability Object#

FieldTypeRequiredDescription
availablebooleanโœ…Indicates if this service option is available for the user.
reasonsArray(string)If the service option is unavailable, this will contain the reasons why.
item_codesArray(string)The item codes which caused the option to be unavailable.

Window Object#

One of the following:

FieldTypeRequiredDescription
start_atstringโœ…The start of the delivery window in ISO 8601 format.
end_atstringโœ…The end of the delivery window in ISO 8601 format.
typestringโœ…The type of service option. One of 'scheduled', 'eta' (contact your Instacart Connect representative), or 'asap' (contact your Instacart Connect representative).
asapbooleanIndicates if delivery will happen as soon as possible. Only true when type is asap.

or

FieldTypeRequiredDescription
immediate_hourintegerโœ…Indicates the number of hours after order creation that delivery will occur.
typestringโœ…Indicates this is an immediate option. Defaults to immediate.

Response Examples#

{  "service_option_hold": {    "id": 3,    "expires_at": "2018-02-22T00:10:00Z",    "service_option": {      "id": 70,      "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": []      }    }  }}