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 address line.

address_line_2stringOptional

The second address line.

address_typestringOptional

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

postal_codestringRequired

The postal/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 ID of the service option.

service_option_referencestringOptional

The reference of the service option.

datestringRequired

The date the service will take place in ISO 8601 format.

handoff_timestringOptional

The ETA for shopper to arrive at store.

windowWindowRequired

The time window when the service will take place.

availabilityOptionAvailabilityRequired

The availability of this service option.

OptionAvailability Object​

FieldTypeRequiredDescription
availablebooleanRequired

Indicates if this service option is available for the user.

reasonsArray(string)Optional

The 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)Optional

The item codes which caused the option to be unavailable.

Window Object​

One of the following:

FieldTypeRequiredDescription
start_atstringRequired

The start of the delivery window in ISO 8601 format.

end_atstringRequired

The end of the delivery window 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 if delivery will happen as soon as possible. Only true when type is asap.

or

FieldTypeRequiredDescription
immediate_hourintegerRequired

Indicates the number of hours after order creation that delivery will occur.

typestringRequired

Indicates this is an immediate option. Defaults to immediate.

Error Object​

FieldTypeRequiredDescription
errorErrorDetailsOptional

Information relevant to the error.

metaMetaErrorOptional

The error metadata.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptional

The error message.

error_codeintegerOptional

The error code.

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": 37,
      "service_option_reference": "ezppZD0-MzcsIDp0eXBlPT4iU2NoZWR1bGVkRGVsaXZlcnlPcHRpb24iLCA6d2luZG93PT48SW5zdGFjYXJ0OjpFbnRlcnByaXNlOjpCb2JhOjpDb3JlOjpUeXBlczo6VjE6OlNlcnZpY2VPcHRpb25TY2hlZHVsZWRXaW5kb3c6IGRlc2NyaXB0b3I6ICIiLCBzdGFydF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI1NzYwMCwgbmFub3M6IDA-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"}
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"invalid_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