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 to do the following things:

  • Contact your Instacart Connect representative and ask them to enable the ETA service option in your retailer configuration.
  • Implement the delivery, last mile delivery, or pickup workflows on your site.

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 request both 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 a scheduled time slot. 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 on 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.

Last updated on