Skip to main content

Preview time slots for last mile delivery

POST /v2/fulfillment/service_options/last_mile

Lists the available delivery service options for the customer's location. In this context, service options are time slots, such as Today 4pm-6pm or Friday 9am-11am. Availability is based on current and anticipated shopper availability for the relevant store and delivery location.

Use this endpoint when you want to display a list of available time slots before a customer logs in or starts shopping. The list includes immediate and scheduled time slots. To get an ETA time slot with the scheduled time slots, set the with_eta_options field to true. For more information about ETAs and the preview scenario, see Service options.

If you permit a potential customer to select a preview time slot, save the service_option_id. You specify the ID when reserving the time slot.

If you don't permit a potential customer to select a preview time slot, or if you need to prompt the customer to pick a different time slot, call List time slots for last mile delivery at checkout.

Best practice

Order creation might fail because the preview time slot isn't available anymore when the customer checks out. To reduce the chance of order creation failing, call List time slots for last mile delivery to get a list of validated time slots. Save the service_option_id, and then call Reserve a time slot.

Security​

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters​

None.

Request​

FieldTypeRequiredDescription
location_codestringOptionalLocation code of the store where the delivery driver picks up the order. Either postal code or location code is required.
postal_codestringOptionalThe postal code for delivery. Either postal code or location code is required.
cart_total_centsintegerOptionalThe total value of all items for the order in cents.
items_countintegerOptionalThe number of different types of items in the order.
earliest_option_start_atstringOptionalThe earliest time that an order can be ready for delivery. Only time slots that start after this time are retrieved.
units_countnumberOptionalThe number of all items, including multiples of an item, in the order.
with_eta_optionsbooleanOptionalReturns ETA options instead of immediate options when true. For more information, contact your Instacart Representative. Defaults to false.
with_priority_eta_optionsbooleanOptionalReturns Priority ETA options instead of immediate options when true. For more information, contact your Instacart Representative. Defaults to false.
with_handoff_timebooleanOptionalIndicator whether the handoff time is calculated when fetching service option. Defaults to false.
desired_windowsArray(DesiredWindow)OptionalThe desired windows for service options.

DesiredWindow Object​

FieldTypeRequiredDescription
starts_atstringRequiredStart time of the desired window in ISO 8601 format.
ends_atstringRequiredEnd time of the desired window in ISO 8601 format.
info

You can specify either the customer’s postal_code (recommended) or the store’s location_code as the required field for this request. For the most accurate set of time slots for the delivery address, specify the postal_code. If both fields are specified, the store’s address is used, which might return a different set of time slots.

Request examples​

curl --request POST \
  --url https://connect.instacart.com/v2/fulfillment/service_options/last_mile \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_code": "string",
  "postal_code": "string",
  "cart_total_cents": 1,
  "items_count": 1,
  "earliest_option_start_at": "string",
  "units_count": 1,
  "with_eta_options": true,
  "with_priority_eta_options": true,
  "with_handoff_time": true,
  "desired_windows": [
    {
      "starts_at": "string",
      "ends_at": "string"
    }
  ]
}'

Response​

FieldTypeRequiredDescription
service_optionsArray(ServiceOption)RequiredThe returned service options.

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
Unmatched city and countyThe city and county of the store and customer must match.

Response examples​

200 Success

{
  "service_options": [
    {
      "id": 356,
      "service_option_reference": "ezppZD0-MzU2LCA6dHlwZT0-OSwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-21",
      "window": {
        "start_at": "2018-02-22T02:00:00Z",
        "end_at": "2018-02-22T04:00:00Z",
        "type": "scheduled",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 357,
      "service_option_reference": "ezppZD0-MzU3LCA6dHlwZT0-NCwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-21",
      "window": {
        "immediate_hour": 2,
        "type": "immediate"
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 358,
      "service_option_reference": "ezppZD0-MzU4LCA6dHlwZT0-NywgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTcxMjc2MTkwOCwgbmFub3M6IDMwMDMyNzAwMD4sIGVuZHNfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE3MTI3NjkxMDgsIG5hbm9zOiAzMDAzMjcwMDA-Pn0=",
      "date": "2024-04-10",
      "window": {
        "start_at": "2024-04-10T15:11:48Z",
        "end_at": "2024-04-10T17:11:48Z",
        "type": "eta",
        "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
400Handoff time is requested but not configured"Handoff time calculation is not configured for this retailer."1001{"key":"with_handoff_time"}
400Missing postal code"location_code or postal_code required"1001{"key":"base"}
400Invalid location code"Specified store is not available for lastmile."1001{"key":"location_code"}
400Invalid postal code for store"We do not currently support delivery from this store to the selected postal_code."1001{"key":"postal_code"}
404Resource not found"Resource not found"4000Not applicable
Last updated on