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.

Order item limitations​

If your request specifies an order containing items that exceed any of the following limitations, the request fails:

  • Maximum total quantity of items
  • Maximum total weight of beverage items
  • Maximum quantity of large or bulky items

For more information, see the returned error message.

Security​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequired

The ID of the user.

Request​

Each items[] in the request requires either a count or a weight. The field that needs to be defined depends on that product's catalog configuration. For more information, see Product quantity types.

FieldTypeRequiredDescription
addressExpandedAddressRequired

The address for the delivery.

itemsArray(OrderItem)Required

The items for delivery.

desired_windowsArray(DesiredWindow)Optional

The desired windows for service options.

location_codestringOptional

The store location code used to look-up cart items.

with_eta_optionsbooleanOptional

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

with_priority_eta_optionsbooleanOptional

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

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.

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequired

The item's line number in the order.

countintegerOptional

The count of the item. Must be a non-negative integer. Depending on the item's catalog configuration, either this field or 'weight' is required.

weightnumberOptional

For items sold by weight, the numerical weight of the item. Depending on the item's catalog configuration, either this field or 'count' is required. 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_instructionsstringOptional

Any special instructions about the item selection.

replacement_policystringOptional

One of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).

metadataHashOptional

The item-level metadata.

replacement_itemsArray(Replacement_items)Optional

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.

itemItemRequired

The item's code.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

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/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",
    "city": "string"
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "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(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
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": 32,
      "service_option_reference": "ezppZD0-MzIsIDp0eXBlPT45LCA6d2luZG93PT48SW5zdGFjYXJ0OjpDdXN0b21lcnM6OkF2YWlsYWJpbGl0eTo6VjE6OlRpbWVzdGFtcFdpbmRvdzogc3RhcnRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjY0ODAwLCBuYW5vczogMD4sIGVuZHNfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNzIwMDAsIG5hbm9zOiAwPj59",
      "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": 33,
      "service_option_reference": "ezppZD0-MzMsIDp0eXBlPT40LCA6d2luZG93PT48SW5zdGFjYXJ0OjpDdXN0b21lcnM6OkF2YWlsYWJpbGl0eTo6VjE6OlRpbWVzdGFtcFdpbmRvdzogc3RhcnRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjY0ODAwLCBuYW5vczogMD4sIGVuZHNfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNzIwMDAsIG5hbm9zOiAwPj59",
      "date": "2018-02-21",
      "window": {
        "immediate_hour": 2,
        "type": "immediate"
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    },
    {
      "id": 34,
      "service_option_reference": "ezppZD0-MzQsIDp0eXBlPT43LCA6d2luZG93PT48SW5zdGFjYXJ0OjpDdXN0b21lcnM6OkF2YWlsYWJpbGl0eTo6VjE6OlRpbWVzdGFtcFdpbmRvdzogc3RhcnRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNzc2MjgxNzgwLCBuYW5vczogMjA0NTU3MDAwPiwgZW5kc19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTc3NjI4ODk4MCwgbmFub3M6IDIwNDU1NzAwMD4-fQ==",
      "date": "2026-04-15",
      "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": []
      }
    }
  ],
  "warnings": [
    {
      "error": {
        "message": "1 item not found.",
        "error_code": 2000
      },
      "meta": {
        "items": [
          {
            "item_code": "000000004011"
          }
        ]
      }
    }
  ]
}

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 stores found"No store location found for given address."1001{"key":"address"}
400Invalid items"1 item not found."2000{"upcs":["123"],"items":[{"item_upc":"123"}],"error_name":"ItemNotFoundError"}
400Insufficient items to meet order pass threshold"1 item not found. Insufficient items to meet order pass threshold."2008{"upcs":["123"],"items":[{"item_upc":"123"}],"item_found_ratio":0.5,"min_item_found_ratio":0.8,"total_cost_cents":1000,"min_total_cost_cents":2000,"error_name":"InsufficientItemsError"}
400Invalid params"There were issues with your request"1001Not applicable
400Address contains PO box"address contains PO Box"1001{"key":"address"}
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"}
400Without items"can't be blank"1001{"key":"items"}
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"}
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"}
400Duplicate items were provided"Duplicate items provided for this order."2007{"duplicate_items":[{"item_rrc":1234,"item_upc":"0001234567892","line_num":2}],"error_name":"DuplicateItemsError"}
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"}
400Some items are not deliverable"Some items are not deliverable"2005{"items":[{"item_rrc":"133631"},{"item_rrc":"133631"}]}
400Too many items"The number of items in your cart exceeds our maximum limit for a single delivery. Please remove 10 items from your cart to continue."2024Not applicable
400Too much beverage"The weight of beverages in your cart exceeds our maximum limit for a single delivery. Please remove 150 lbs of beverages from your cart to continue."2026Not applicable
400Too many big and bulky items"The number of big and bulky items in your cart exceeds our maximum limit for a single delivery. Please remove 2 such items from your cart to continue."2023{"items":[]}
400Too much weight"The total weight of items in your cart exceeds our maximum limit for a single delivery. Please remove 15 lb from your cart to continue."2027{"over_weight_amount":15,"weight_unit":"lb"}
403User Not Active"User Not Active"nullNot applicable
404Resource not found"Resource not found"4000Not applicable
Last updated on