Skip to main content

Reserve a time slot for a desired window

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

Reserves the selected time slot for a desired window (service_option_reference) 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 desired windows, see Desired windows.

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

Request

FieldTypeRequiredDescription
service_option_referencestringRequiredThe reference of the service option.

Request examples

curl --request POST \
--url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/service_options/reserve' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"service_option_reference": "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.

Reasons for unavailability of a service option

ReasonDescription
State law restricts amount of {beer/wine/spirits} to {#} fl oz, cart quantity is: {#} fl oz.The quantity of this alcohol type exceeds the state law limit.
Error validating alcohol quantities. Please try again.The quantity of alcohol can’t be validated.
Unmatched city and countyThe city and county of the store and customer must match.
Cannot deliver alcohol to this postal codeInstacart can’t deliver alcohol to this postal code.
State law doesn't allow delivery of alcohol in this windowInstacart can’t deliver alcohol in this delivery window because of state law.
Unfortunately alcohol pickup is not available at this location. Please remove alcohol from your basket or try delivery.Alcohol pickup is not available at this location.

Response examples

200 Success

{
"service_option_hold": {
"id": 159,
"expires_at": "2018-02-22T00:10:00Z",
"service_option": {
"id": 258,
"service_option_reference": "PEluc3RhY2FydDo6QXZhaWxhYmlsaXR5OjpWMTo6T3B0aW9uOiBpZDogMjAs\nIGJ1c3lfc3VyY2hhcmdlOiAwLjAsIHRpbWVfd2luZG93OiA8SW5zdGFjYXJ0\nOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19h\ndDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUx\nOTI2NDgwMCwgbmFub3M6IDA+LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1\nZjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4s\nIGV4dGVybmFsX2lkOiAiIj4sIHpvbmVfaWQ6IDIwLCB3YXJlaG91c2VfaWQ6\nIDIwLCB0eXBlOiA6U0NIRURVTEVEX0RFTElWRVJZX09QVElPTiwgaXNfcHJp\nb3JpdHlfc3VyZ2U6IGZhbHNlLCBzZXJ2aWNlX29wdGlvbl9yZWY6ICIiLCBh\ndmFpbGFibGU6IGZhbHNlLCB1bmF2YWlsYWJsZV9yZWFzb246IFtdLCBleHRl\ncm5hbF9pZDogIiIsIHNlcnZpY2Vfb3B0aW9uX3Rva2VuOiAiIiwgZGV0YWls\nZWRfdW5hdmFpbGFibGVfcmVhc29uOiBbXT4=\n",
"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
400Retry later"Please try again in a little while"2003Not applicable
400User Not Found"User Not Found"1001{"key":"user_id"}
400Blank service option reference"can't be blank"1001{"key":"service_option_reference"}
400Service Option Expired"The requested ETA option has expired."1001{"key":"service_option_id"}
403Inactive user"User Not Active"nullNot applicable
404Resource not found"Resource not found"4000Not applicable