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_idpathstringRequiredThe ID of the user.

Request​

FieldTypeRequiredDescription
addressAddressRequiredThe address of the user.
location_codestringRequiredLocation code of the store where the delivery driver picks up the order.
cart_total_centsintegerRequiredThe total value of all items for the order in cents.
items_countintegerRequiredThe number of different types of items in the order.
units_countnumberOptionalThe number of all items, including multiples of an item, 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.
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.

Address Object​

FieldTypeRequiredDescription
address_line_1stringRequiredThe first address line.
address_line_2stringOptionalThe second address line.
address_typestringOptionalThe type of address, e.g., "residential".
postal_codestringRequiredThe postal/zip code of the address.

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.

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"
  },
  "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)RequiredThe returned service options.
warningsArray(Error)OptionalAny warnings associated with this request.
flagsFlagsOptionalAdditional properties of the address.

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', or 'priority_eta'. To enable 'eta' or 'priority_eta', 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.

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptionalInformation relevant to the error.
metaMetaErrorOptionalThe error metadata.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptionalThe error message.
error_codeintegerOptionalThe error code.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)OptionalThe items that triggered the error.

ItemInfo Object​

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

Flags Object​

FieldTypeRequiredDescription
long_distance_deliverybooleanOptionalWhether 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": 40,
      "service_option_reference": "ezppZD0-NDAsIDp0eXBlPT4iU2NoZWR1bGVkRGVsaXZlcnlPcHRpb24iLCA6d2luZG93PT48SW5zdGFjYXJ0OjpFbnRlcnByaXNlOjpCb2JhOjpDb3JlOjpUeXBlczo6VjE6OlNlcnZpY2VPcHRpb25TY2hlZHVsZWRXaW5kb3c6IGRlc2NyaXB0b3I6ICIiLCBzdGFydF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI1NzYwMCwgbmFub3M6IDA-LCBlbmRfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNjQ4MDAsIG5hbm9zOiAwPj59",
      "date": "2018-02-22",
      "window": {
        "start_at": "2018-02-22T00:00:00Z",
        "end_at": "2018-02-22T02:00:00Z",
        "type": "scheduled",
        "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"}
400Invalid location code"Specified store is not available for lastmile."1001{"key":"location_code"}
400No stores found"No store location found for given address."1001Not applicable
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