Skip to main content

List time slots for last mile delivery

POST /v2/fulfillment/users/{user_id}/service_options/cart/last_mile

Lists the available last mile delivery service options for the customer's location and cart details. 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.

By default, the time slots returned are immediate and scheduled time slots. If ETA options are enabled in your retailer configuration, you can retrieve ETA time slots instead of immediate time slots. To get a standard ETA time slot with the scheduled time slots, set the with_eta_options field to true. To also retrieve a priority ETA time slot, set the with_priority_eta_options field to true. For more information, see Retrieve an ETA time slot.

If the location_code in the request references a store that offers long-distance deliveries and Instacart estimates the delivery time to be between 30 and 60 minutes, inclusive, then flags.long_distance_delivery is set to true. For more information, see Service areas for delivery.

After a time slot is selected, save the service_option_id. You specify the ID when reserving the time slot.

tip

This operation differs from preview service options in that the service enforces all the parameters necessary to return accurate, complete service options. Use this operation when the customer is ready to check out.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequired

The ID of the user.

Request​

FieldTypeRequiredDescription
addressExpandedAddressRequired

The address of the user.

location_codestringRequired

Location code of the store where the delivery driver picks up the order.

cart_total_centsintegerRequired

The total value of all items for the order in cents.

items_countintegerRequired

The number of different types of items in the order.

units_countnumberOptional

The number of all items, including multiples of an item, in the order.

earliest_option_start_atstringOptional

The earliest time that an order can be ready for delivery. Only time slots that start after this time are retrieved.

with_eta_optionsbooleanOptional

Returns ETA options instead of immediate options when true. For more information, contact your Instacart Representative. Defaults to false.

with_priority_eta_optionsbooleanOptional

Returns Priority ETA options instead of immediate options when true. For more information, contact your Instacart Representative. Defaults to false.

with_handoff_timebooleanOptional

Indicator whether the handoff time is calculated when fetching service option. Defaults to false.

desired_windowsArray(DesiredWindow)Optional

The desired windows for service options.

ExpandedAddress Object​

FieldTypeRequiredDescription
address_line_1stringRequired

The first line of the address, e.g., 123 Main St.

address_line_2stringOptional

The second line of the address, e.g., Apt 4B.

address_typestringOptional

The type of address, e.g., residential.

postal_codestringRequired

The postal or zip code of the address.

citystringOptional

The city or town of the address, e.g., Chicago.

DesiredWindow Object​

FieldTypeRequiredDescription
starts_atstringRequired

Start time of the desired window in ISO 8601 format.

ends_atstringRequired

End time of the desired window in ISO 8601 format.

Request examples​

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/service_options/cart/last_mile' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "address": {
    "address_line_1": "string",
    "address_line_2": "string",
    "address_type": "string",
    "postal_code": "string",
    "city": "string"
  },
  "location_code": "string",
  "cart_total_cents": 1,
  "items_count": 1,
  "units_count": 1,
  "earliest_option_start_at": "string",
  "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)Required

The returned service options.

warningsArray(Error)Optional

Any warnings associated with this request.

flagsFlagsOptional

Additional properties of the address.

ServiceOption Object​

FieldTypeRequiredDescription
idintegerRequired

The service option ID.

service_option_referencestringOptional

A unique service option reference that acts as a token you pass in downstream requests to place a hold.

datestringRequired

The date and time the service is scheduled to take place in ISO 8601 format.

handoff_timestringOptional

Indicates in ISO 8601 format when the handoff between the store associate and the Instacart shopper is expected to occur. Only applicable to last mile delivery orders and not supported in Fulfillment API v3.

windowWindowRequired

The fulfillment window.

availabilityOptionAvailabilityRequired

Indicates whether the service option is available and, if it's not, provides details about why.

OptionAvailability Object​

FieldTypeRequiredDescription
availablebooleanRequired

Indicates whether the service option is available. If false, then it cannot be selected. In this case, reasons and item_codes indicate why the service option isn’t available and which items caused the unavailability.

reasonsArray(string)Optional

If available is false, this field lists the reasons why. Currently, these reasons, which are subject to change without notice, all relate to restrictions on the sale of alcohol. For more information, see Unavailability Reasons.

item_codesArray(string)Optional

The codes of the items which caused the service option to be unavailable.

Window Object​

One of the following:

FieldTypeRequiredDescription
start_atstringRequired

The delivery window's starting date and time in ISO 8601 format.

end_atstringRequired

The delivery window's ending date and time in ISO 8601 format.

typestringRequired

The type of service option. One of scheduled, eta, or priority_eta. To enable eta or priority_eta, contact your Instacart Connect representative.

asapbooleanOptional

Indicates whether delivery is scheduled to occur as soon as possible.

or

FieldTypeRequiredDescription
immediate_hourintegerRequired

The number of hours from the time of order creation by which fulfillment is expected to be complete. For example, if immediate_hour is 2 and the order is created at 9:00am, fulfillment should complete by 11:00am.

typestringRequired

Indicates that the service option is immediate. Defaults to immediate.

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptional

The error details.

metaMetaErrorOptional

Metadata about the error, including the items associated with it.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptional

A human-readable description of the error.

error_codeintegerOptional

A numeric code that identifies the error type.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)Optional

The items that triggered the error.

ItemInfo Object​

FieldTypeRequiredDescription
item_codestringOptional

The retailer reference code (RRC) or universal product code (UPC) of an item that triggered the error.

Flags Object​

FieldTypeRequiredDescription
long_distance_deliverybooleanOptional

Whether a delivery to the address will be a long distance delivery.

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": 327,
      "service_option_reference": "ezppZD0-MzI3LCA6dHlwZT0-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": 328,
      "service_option_reference": "ezppZD0-MzI4LCA6dHlwZT0-NCwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "date": "2018-02-21",
      "window": {
        "immediate_hour": 2,
        "type": "immediate"
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 329,
      "service_option_reference": "ezppZD0-MzI5LCA6dHlwZT0-NywgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTc3NjI4MTc4MCwgbmFub3M6IDIwNDU1NzAwMD4sIGVuZHNfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE3NzYyODg5ODAsIG5hbm9zOiAyMDQ1NTcwMDA-Pn0=",
      "date": "2026-04-15",
      "handoff_time": "2018-02-22T00:30:00Z",
      "window": {
        "start_at": "2026-04-15T19:36:20Z",
        "end_at": "2026-04-15T21:36:20Z",
        "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"}
400Address contains PO box"address contains PO Box"1001{"key":"address"}
400Invalid location code"Specified store is not available for lastmile."1001{"key":"location_code"}
400No stores found"No store location found for given address."1001{"key":"address_line_1"}
400Cannot deliver to address"Unfortunately, we cannot deliver to that area."1001{"key":"address"}
400Store does not support delivery to address"We do not currently support delivery from this store to the selected address."1001{"key":"address"}
400User Not Found"User Not Found"1001{"key":"user_id"}
404Resource not found"Resource not found"4000Not applicable
Last updated on