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 2 hours of creating the order or tomorrow between 2pm and 4pm. Availability is based on current and anticipated shopper availability for the relevant store and delivery location.

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

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#

NameInRequiredDescription
user_idpathβœ…The ID of the user.

Request#

FieldTypeRequiredDescription
addressAddressβœ…The address for the delivery.
itemsArray(Items)βœ…The items for delivery.
location_codestringThe store location code used to look-up cart items.

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.
weightnumberThe weight of the item (defaults to lbs in the US). 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.
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).

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"      }    }  ],  "location_code": "string"}'

Response#

FieldTypeRequiredDescription
service_optionsArray(Service_options)βœ…The returned service options.

Service_options Object#

FieldTypeRequiredDescription
idintegerβœ…The ID of the service option.
datestringβœ…The date the service will take place in ISO 8601 format.
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)If the service option is unavailable, this will contain the reasons why.
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.

Response Examples#

{  "service_options": [    {      "id": 1,      "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": []      }    },    {      "id": 2,      "date": "2018-02-22",      "window": {        "immediate_hour": 5,        "type": "immediate"      },      "availability": {        "available": true,        "reasons": [],        "item_codes": []      }    },    {      "id": 3,      "date": "2018-02-22",      "window": {        "start_at": "2018-02-22T00:00:00Z",        "end_at": "2018-02-22T02:00:00Z",        "type": "eta",        "asap": false      },      "availability": {        "available": true,        "reasons": [],        "item_codes": []      }    },    {      "id": 4,      "date": "2018-02-22",      "window": {        "start_at": "2018-02-22T00:00:00Z",        "end_at": "2018-02-22T02:00:00Z",        "type": "asap",        "asap": true      },      "availability": {        "available": true,        "reasons": [],        "item_codes": []      }    }  ]}