Skip to main content

Reserve a time slot

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

Reserves the selected time slot (service_hold_id) for the specified user ID. Time slots are reserved for 10 minutes. If the reservation expires before you can create the order, you can attempt to reserve the same time slot. If the time slot still has capacity, the request is successful. 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.


AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.


user_idpathstringโœ…The ID of the user.
service_option_idpathintegerโœ…The ID of the service option.

Request Examples#

curl --request POST \  --url '{user_id}/service_options/{service_option_id}/reserve' \  --header 'Accept: application/json' \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json'


service_option_holdService_option_holdโœ…The created service option hold.

Service_option_hold Object#

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#

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#

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:

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.


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