Skip to main content

How to retrieve ETA time slots

When listing the delivery time slots for your customers to reserve, you can choose to present estimated time of arrival (ETA) time slots. The ETA service options replace the immediate time slots of within 2 or 5 hours. For more information, see Service options.

You can choose to retrieve a standard ETA time slot, a priority ETA time slot, or both.

Prerequisites

You need the following things:

The ETA service option is currently not supported for pickup orders.

Update your retailer site

Update your storefront to be able to show the ETA service options you want to offer.

The following image shows a priority ETA, standard ETA, and the scheduled options. The ETA options have the word "By" and the expected delivery by time. The priority option has a lightening bolt.

The image shows a priority ETA time slot with the text "By 12:00pm Priority +$2" and a standard ETA time slot with the text "By 1:10pm Standard Free".

Retrieve time slots

When your site sends requests to retrieve the list of available time slots, specify one or both types of ETA options in the request body. The response contains the ETA time slots plus scheduled time slots. If an ETA time slot is not available, the scheduled time slots start from the next hour after the request is made.

The following example from the Implement delivery tutorial has been modified to retrieve both types of ETA service options: with_eta_options and with_priority_eta_options.

curl --request POST \
--url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/service_options/cart' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"with_eta_options": true,
"with_priority_eta_options": true,
"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 priority ETA time slot, a standard ETA time slot, and scheduled time slots. Timestamps are returned in Coordinated Universal Time (UTC).

{
"service_options": [
{
"id": 140295945,
"date": "2021-10-15",
"window": {
"start_at": "2021-10-15T21:00:54Z",
"end_at": "2021-10-15T23:0:00Z",
"type": "scheduled",
"asap": false
},
"availability": {
"available": true,
"reasons": [],
"item_codes": []
}
},
{
"id": 168098620,
"date": "2021-10-15",
"window": {
"start_at": "2021-10-15T17:43:54Z",
"end_at": "2021-10-15T20:10:00Z",
"type": "eta",
"asap": false
},
"availability": {
"available": true,
"reasons": [],
"item_codes": []
}
},
{
"id": 582259071,
"date": "2021-10-15",
"window": {
"start_at": "2021-10-15T17:43:04Z",
"end_at": "2021-10-15T19:00:00Z",
"type": "priority_eta",
"asap": false
},
"availability": {
"available": true,
"reasons": [],
"item_codes": []
}
}
]
}

In this response, the service option 168098620 is the standard ETA time slot. The start_at timestamp is the current time, while the end_at timestamp is the latest delivery time. The order should arrive at the customer by or before the end_at time.

Reserve the ETA time slot

Reserve an ETA time slot as usual by specifying its service option ID. If the ETA time slot expires before your site reserves it, the following error occurs.

{
"error": {
"message": "The requested ETA option has expired.",
"code": 1001
},
"meta": {
"key": "service_option_id"
}
}

To get new ETA options, refresh the list of time slots. See Retrieve time slots.

Create the order

Create the order with the service option hold ID as usual. In the response, the fulfillment_details.window_ends_at field contains the correct ETA timestamp. If the reservation expires before your site creates the order, the following error occurs.

{
"error": {
"message": "ETA option hold has expired.",
"code": 1001
},
"meta": {
"key": "service_option_hold_id"
}
}

To get new ETA options, refresh the list of time slots. See Retrieve time slots.

What's next?

In a delivery workflow, after the order is created successfully with an ETA time slot, the order is batched. A shopper is assigned the batch. a shopper begins shopping with enough time to fulfill and deliver the order by the ETA.

In a last mile delivery workflow, when an order is ready or when a prepared food order will be ready to be picked up soon, your retailer site calls the Stage an order endpoint, which updates the order status to staged. Instacart batches the order immediately and a shopper can accept the batch for delivery. Your platform receives an At store callback when the shopper is at the store to pick up the order.

In either case, if a shopper is delayed, your platform receives a Late delivery callback and the customer receives a Late delivery customer notification with an updated ETA.