Skip to main content

List time slots for delivery

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

Lists the available delivery service options for the customer's location and cart items. In this context, service options are time slots, such as Within 5 hours 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 customer address is more than 30 minutes away from the selected store, the long_distance_delivery flag is set to true. You can deliver to this address if long distance delivery is enabled for the store. For more information, see Service areas for delivery.

If you’d like more flexibility with your time slots, you can send Instacart your desired windows. Instacart uses your desired windows to map to available service options and returns the available time slots for the desired windows. For more information, see Desired windows.

After a time slot is selected, save the service_option_id or service_option_reference.

  • To reserve a time slot for a desired window, you specify the service_option_reference.
  • To reserve a time slot without a desired window, you specify the service_option_id.
Best practice

Include all the items in the cart in the request. Connect can surface any errors—such as items missing from the catalog—early in the user flow and also precompute some validations to optimize performance.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstring✅The ID of the user.

Request​

FieldTypeRequiredDescription
addressAddress✅The address for the delivery.
itemsArray(Items)✅The items for delivery.
desired_windowsArray(Desired_windows)The desired windows for service options.
location_codestringThe store location code used to look-up cart items.
with_eta_optionsbooleanReturns ETA options instead of immediate when true. For more information, contact your Instacart Representative. Defaults to false.
with_priority_eta_optionsbooleanReturns Priority ETA options instead of immediate when true. For more information, contact your Instacart Representative. Defaults to false.

Address Object​

FieldTypeRequiredDescription
address_line_1string✅The first address line.
address_line_2stringThe second address line.
address_typestringThe type of address, e.g., "residential".
postal_codestring✅The postal/zip code of the address.

Items Object​

FieldTypeRequiredDescription
line_numstring✅The item's line number in the order.
countintegerThe count of the item. Must be a non-negative integer.
weightnumberFor items sold by weight, the numerical weight of the item. The API interprets this value as whatever unit of measure is defined for the item in the catalog, such as lb or kg. Must be a non-negative number.
special_instructionsstringAny special instructions about the item selection.
replacement_policystringOne of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
replacement_itemsArray(Replacement_items)A list of requested replacement items if the original item could not be found. This field needs to be turned on via configuration. Contact your Instacart Connect representative.
itemItem✅The item's code.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstring✅The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstring✅The item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstring✅The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstring✅The item's retailer reference code (rrc).

Desired_windows Object​

FieldTypeRequiredDescription
starts_atstring✅Start time of the desired window in ISO 8601 format.
ends_atstring✅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/delivery' \
  --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"
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ],
  "desired_windows": [
    {
      "starts_at": "string",
      "ends_at": "string"
    }
  ],
  "location_code": "string",
  "with_eta_options": true,
  "with_priority_eta_options": true
}'

Response​

FieldTypeRequiredDescription
service_optionsArray(Service_options)✅The returned service options.
warningsArray(Warnings)Any warnings associated with this request.
flagsFlagsAdditional properties of the address.

Service_options Object​

FieldTypeRequiredDescription
idinteger✅The ID of the service option.
service_option_referencestringThe reference of the service option.
datestring✅The date the service will take place in ISO 8601 format.
handoff_timestringThe ETA for shopper to arrive at store.
windowWindow✅The time window when the service will take place.
availabilityAvailability✅The availability of this service option.

Availability Object​

FieldTypeRequiredDescription
availableboolean✅Indicates if this service option is available for the user.
reasonsArray(string)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)The item codes which caused the option to be unavailable.

Window Object​

One of the following:

FieldTypeRequiredDescription
start_atstring✅The start of the delivery window in ISO 8601 format.
end_atstring✅The end of the delivery window in ISO 8601 format.
typestring✅The type of service option. One of 'scheduled', 'eta' (contact your Instacart Connect representative), or 'asap' (contact your Instacart Connect representative).
asapbooleanIndicates if delivery will happen as soon as possible. Only true when type is asap.

or

FieldTypeRequiredDescription
immediate_hourinteger✅Indicates the number of hours after order creation that delivery will occur.
typestring✅Indicates this is an immediate option. Defaults to immediate.

Warnings Object​

FieldTypeRequiredDescription
errorErrorInformation relevant to the error.
metaMetaThe error metadata.

Error Object​

FieldTypeRequiredDescription
messagestringThe error message.
error_codeintegerThe error code.

Meta Object​

FieldTypeRequiredDescription
itemsArray(Items)The items that triggered the error.

Items Object​

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

Flags Object​

FieldTypeRequiredDescription
long_distance_deliverybooleanWhether a delivery to the address will be a long distance delivery.

Reasons for unavailability of a service option​

ReasonDescription
State law restricts amount of {beer/wine/spirits} to {#} fl oz, cart quantity is: {#} fl oz.The quantity of this alcohol type exceeds the state law limit.
Error validating alcohol quantities. Please try again.The quantity of alcohol can’t be validated.
Unmatched city and countyThe city and county of the store and customer must match.
Cannot deliver alcohol to this postal codeInstacart can’t deliver alcohol to this postal code.
State law doesn't allow delivery of alcohol in this windowInstacart can’t deliver alcohol in this delivery window because of state law.

Response examples​

200 Success

{
  "service_options": [
    {
      "id": 9,
      "service_option_reference": "ezppZD0-OSwgOnR5cGU9PiJTY2hlZHVsZWREZWxpdmVyeU9wdGlvbiIsIDp3aW5kb3c9PjxJbnN0YWNhcnQ6OkVudGVycHJpc2U6OkJvYmE6OkNvcmU6OlR5cGVzOjpWMTo6U2VydmljZU9wdGlvblNjaGVkdWxlZFdpbmRvdzogZGVzY3JpcHRvcjogIiIsIHN0YXJ0X2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjU3NjAwLCBuYW5vczogMD4sIGVuZF9hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-Pn0=",
      "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": false,
        "reasons": [
          "State law doesn't allow delivery of alcohol in this window"
        ],
        "item_codes": [
          "000000004011"
        ]
      }
    }
  ],
  "warnings": []
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400User Not Found"User Not Found"1001{"key":"user_id"}
400Invalid location code"Could not find specified store."1001{"key":"location_code"}
400No weight or count provided*"There were issues with your request"9999{}
400No stores found"No store location found for given address."1001{}
400Invalid items"1 item not found."2000{"upcs":["123"],"items":[{"item_upc":"123"}]}
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"}
400Invalid Quantity, expected weight"One of these items had an invalid quantity amount, 0001234567892 expected weight"2012{"upc":"0001234567892","item_code":"0001234567892","expected_param":"weight","error_name":"WrongQuantityParameterError"}
400Invalid Quantity, expected count"One of these items had an invalid quantity amount, 0001234567892 expected count"2012{"upc":"0001234567892","item_code":"0001234567892","expected_param":"count","error_name":"WrongQuantityParameterError"}
400Duplicate items were provided"Duplicate items provided for this order."2007{"duplicate_items":[{"item_upc":"123456789999","item_rrc":null,"line_num":"0"},{"item_upc":"123456789999","item_rrc":null,"line_num":"1"}]}
400Priority ETA options not configured"Priority ETA options are not configured for this retailer."1001{"key":"filters.with_priority_eta_options"}
400ETA options not configured"ETA options are not configured for this retailer."1001{"key":"filters.with_eta_options"}
400Without address"can't be blank"1001{"key":"address"}
400Invalid Quantity, expected count or weight"One of these items had an invalid quantity amount, 0001234567892 expected count or weight"2012{"upc":"0001234567892","item_code":"0001234567892","expected_param":"count or weight","error_name":"WrongQuantityParameterError"}
403User Not Active"User Not Active"null{}
404Resource not found"Resource not found"4000{}
* Multiple error
Last updated on