Skip to main content

How to support time-sensitive last mile delivery

Time-sensitive last mile delivery orders, such as order ahead meals, require careful coordination between retailers and shoppers. To ensure the shopper arrives as close as possible to the time the meal is prepared, Instacart calculates the handoff time. The handoff time is the time when a shopper is expected to reach the food counter.

When you retrieve time slots, set the with_handoff_time flag to true. Instacart calculates the handoff time with the ETA time slots. Then when you create the order, set the with_handoff_time flag to true to use the calculated handoff time.

Prerequisites​

You need the following things:

  • The Priority ETA service option is enabled in your retailer configuration. Contact your Instacart Connect representative.
  • The Last mile delivery workflow is implemented on your site.
tip

To improve accuracy and determine the estimated time of arrival of the shopper to the store location, enable the At store ETA event callback. Contact your Instacart Connect representative to enable the callback.

Time-sensitive last mile delivery workflow​

The following example shows the process for a time-sensitive last mile delivery:

  1. Customer fills their cart with order ahead meals, starts the checkout process, and then selects delivery.
  2. Customer chooses a delivery time slot. When the time slots are requested, the retailer sets the with_handoff_time flag to true, and Instacart calculates the handoff time for the order. Based on the handoff time, retailers can determine whether they can fulfill the order.
  3. Retailer site prompts the customer details and a payment method.
  4. Customer places the order.
  5. Retailer creates the order with the with_handoff_time flag set to true and the order is created with the previously returned handoff time.
  6. Instacart batches the order so that the shopper arrives close to the handoff time.
  7. Retailer employee starts preparing the food based on the handoff time returned.
  8. Shopper picks up the food at the food counter and delivers it to the customer.

Retrieve time slots with handoff time​

When your site sends requests to retrieve the list of available time slots, specify the ETA options and set the with_handoff_time flag to true in the request body. The with_handoff_time flag determines whether Instacart calculates the handoff time when retrieving the ETA time slots.

The following example from the Implement last mile delivery tutorial has been modified to retrieve the ETA service options and the handoff time: with_eta_options, with_priority_eta_options, and with_handoff_time.

curl --request POST \
    --url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/service_options/cart/last_mile' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <token>' \
    --header 'Content-Type: application/json' \
    --data '{
    "address": {
        "address_line_1": "50 Beale St",
        "postal_code": "94105"
    },
    "cart_total_cents": 2500,
    "items_count": 5,
    "location_code": "<location_code>",
    "with_eta_options": true,
    "with_priority_eta_options": true,
    "with_handoff_time": true
}

The response contains the handoff time. Timestamps are returned in Coordinated Universal Time (UTC).

{
  "service_options": [
    {
      "id": 274,
      "date": "2022-02-22",
      "handoff_time": "2022-02-22T00:30:00Z",
      "window": {
        "start_at": "2022-02-22T00:00:00Z",
        "end_at": "2022-02-22T02:00:00Z",
        "type": "eta",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    }
  ]
}

Create the time-sensitive last mile delivery order​

Create the order with the with_handoff_time flag set to true to create the order with the calculated handoff time.

The following example shows the with_handoff_time flag set to true.

curl --request POST \
  --url 'https://<instacart_development_domain>/v2/fulfillment/users/kamalsingh1234/orders/last_mile' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "xyz123456",
    "service_option_hold_id": <service_option_hold_id>,
    "initial_tip_cents": 50001,
    "location_code": "<location_code>",
    "first_name": "kamal",
    "last_name": "singh",
    "user_phone": "8005550101",
    "items_count": 5,
    "items_weight": 5,
    "address": {
        "address_line_1": "50 Beale St",
        "postal_code": "94105
    },
    "with_handoff_time": true
}

The response contains the handoff time. Timestamps are returned in Coordinated Universal Time (UTC).

{
  "id": "xyz123456",
  "status": "created",
  "order_url": "https://example.com/example-order",
  "created_at": "2022-02-22T00:00:00Z",
  "cancellation_reason": "shopper_driven",
  "locale": "en_US",
  "handoff_time": "2022-02-22T00:30:00Z",
  "fulfillment_details": {
    "window_starts_at": "2022-02-22T00:00:00Z",
    "window_ends_at": "2022-02-22T00:30:00Z"
  }
}
Last updated on