How to retrieve time slots for desired windows
By default, when you request a list of time slots for a delivery order, Instacart returns available delivery service options. If you’d like more flexibility with your time slots, when you request a list of time slots for a delivery order, you can also send Instacart your desired windows. For more information, see Desired windows.
Prerequisites
You need the Delivery workflow implemented on your site. To implement this workflow, contact your Instacart representative.
Retrieve time slots for your desired windows
When your site sends requests to retrieve the list of available time slots, specify your desired windows and service options in the request body. The response contains the available time slots.
The following example from the Implement delivery tutorial has been modified to retrieve two desired windows each two hours long.
curl --request POST \
--url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/service_options/cart/delivery' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"desired_windows": [
{
"starts_at": "2022-11-02T16:00:00.00000-00:00",
"ends_at": "2022-11-02T18:00:00.00000-00:00"
},
{
"starts_at": "2022-11-02T18:00:00.00000-00:00",
"ends_at": "2022-11-02T20:00:00.00000-00:00"
}
],
"address" : {
"address_line_1": "50 Beale St",
"postal_code": "94105"
},
"items": [
{
"line_num": "1",
"count": 10,
"weight": 1,
"item": {
"upc": "<item_upc>"
}
}
],
"location_code": "<location_code>
}'
The response contains a list of available time slots. A service_option_reference is associated with each time slot. Use the service_option_reference to reserve a time slot.
{
"service_options": [
{
"id": 1280750203,
"service_option_reference": "eyJpZCI6MTI4MDc1MDIwMywiaG9sZF9pZCI6bnVsbCwic3RhcnRzX2F0IjoiMjAyMi0xMS0wMlQxMTowMDowMC4wMDAtMDU6MDAiLCJlbmRzX2F0IjoiMjAyMi0xMS0wMlQxMzowMDowMC4wMDAtMDU6MDAiLCJ0eXBlIjoiR3JlZW5EZWxpdmVyeU9wdGlvbiJ9.ZDI0NTZmNDI5ZTE0ZjE5YzFiMWY3YjBhYTk5ODk1NDc0OTRmM2Y1NmQ4YTEyNTg3NDlkZjYxYzdhNWI3ZDE0MQ",
"date": "2022-11-02",
"window": {
"start_at": "2022-11-02T16:00:00Z",
"end_at": "2022-11-02T18:00:00Z",
"type": "scheduled",
"asap": false
},
"availability": {
"available": true,
"reasons": [],
"item_codes": []
}
},
{
"id": 1280750211,
"service_option_reference": "eyJpZCI6MTI4MDc1MDIxMSwiaG9sZF9pZCI6bnVsbCwic3RhcnRzX2F0IjoiMjAyMi0xMS0wMlQxMzowMDowMC4wMDAtMDU6MDAiLCJlbmRzX2F0IjoiMjAyMi0xMS0wMlQxNTowMDowMC4wMDAtMDU6MDAiLCJ0eXBlIjoiR3JlZW5EZWxpdmVyeU9wdGlvbiJ9.ZjZhYTdhOWYyYmRkNzQ1OGM4MDQ5MGUyYTYwY2ZmYzI0MDY5MGQ3ODUyNzAyMmEwMDNhOThjODI0NDc1OWZjNw",
"date": "2022-11-02",
"window": {
"start_at": "2022-11-02T18:00:00Z",
"end_at": "2022-11-02T20:00:00Z",
"type": "scheduled",
"asap": false
},
"availability": {
"available": true,
"reasons": [],
"item_codes": []
}
}
],
"warnings": []
}
Reserve a time slot
Reserve a time slot by specifying the service option reference.
curl --request POST \
--url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/service_options/reserve' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"service_option_reference":"eyJpZCI6MTI4MDc1MDIwMywiaG9sZF9pZCI6bnVsbCwic3RhcnRzX2F0IjoiMjAyMi0xMS0wMlQxMTowMDowMC4wMDAtMDU6MDAiLCJlbmRzX2F0IjoiMjAyMi0xMS0wMlQxMzowMDowMC4wMDAtMDU6MDAiLCJ0eXBlIjoiR3JlZW5EZWxpdmVyeU9wdGlvbiJ9.ZDI0NTZmNDI5ZTE0ZjE5YzFiMWY3YjBhYTk5ODk1NDc0OTRmM2Y1NmQ4YTEyNTg3NDlkZjYxYzdhNWI3ZDE0MQ"
}
The response contains the details about the reserved time slot for a desired window with the service option hold ID 491057284.
{
"service_option_hold": {
"id": 491057284,
"expires_at": "2022-09-23T15:53:42Z",
"service_option": {
"id": 1280750203,
"service_option_reference": "eyJpZCI6MTI4MDc1MDIwMywiaG9sZF9pZCI6bnVsbCwic3RhcnRzX2F0IjoiMjAyMi0xMS0wMlQxMTowMDowMC4wMDAtMDU6MDAiLCJlbmRzX2F0IjoiMjAyMi0xMS0wMlQxMzowMDowMC4wMDAtMDU6MDAiLCJ0eXBlIjoiR3JlZW5EZWxpdmVyeU9wdGlvbiJ9.ZDI0NTZmNDI5ZTE0ZjE5YzFiMWY3YjBhYTk5ODk1NDc0OTRmM2Y1NmQ4YTEyNTg3NDlkZjYxYzdhNWI3ZDE0MQ",
"date": "2022-11-02",
"window": {
"start_at": "2022-11-02T16:00:00Z",
"end_at": "2022-11-02T18:00:00Z",
"type": "scheduled",
"asap": false
},
"availability": {
"available": true,
"reasons": [],
"item_codes": []
}
}
}
}
From your response, note the service option hold ID. You specify this ID when creating an order. The reservation is held for 10 minutes. To book the time slot, create the order.
Create a delivery order
Create the order with the service option hold ID as usual. Send a request to create a delivery order as soon as possible after reserving the time slot for a desired window. For more information, see Create a delivery order.
What's next?
In a delivery workflow, after the order is created successfully, the order is batched. A shopper is assigned the batch. A shopper begins shopping with enough time to fulfill and deliver the order.
If a shopper is delayed, your site receives a Late delivery callback and the customer receives a Late delivery customer notification with an updated ETA.