Skip to main content

List time slots for pickup

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

Lists the available pickup 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 location. The list includes immediate and scheduled time slots.

After a time slot is selected, save the service_option_id. You specify the ID 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​

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
itemsArray(OrderItem)Required

The items for delivery.

location_codestringRequired

The location code of the store fulfilling the order.

with_eta_optionsbooleanOptional

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

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).

Request examples​

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/service_options/cart/pickup' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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"
      }
    }
  ],
  "location_code": "string",
  "with_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 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
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.
Unfortunately alcohol pickup is not available at this location. Please remove alcohol from your basket or try delivery.Alcohol pickup is not available at this location.

Response examples​

200 Success

{
  "service_options": [
    {
      "id": 233,
      "service_option_reference": "ezppZD0-MjMzLCA6dHlwZT0-MSwgOndpbmRvdz0-PEluc3RhY2FydDo6Q3VzdG9tZXJzOjpBdmFpbGFiaWxpdHk6OlYxOjpUaW1lc3RhbXBXaW5kb3c6IHN0YXJ0c19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI2NDgwMCwgbmFub3M6IDA-LCBlbmRzX2F0OiA8R29vZ2xlOjpQcm90b2J1Zjo6VGltZXN0YW1wOiBzZWNvbmRzOiAxNTE5MjcyMDAwLCBuYW5vczogMD4-fQ==",
      "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": 234,
      "service_option_reference": "ezppZD0-MjM0LCA6dHlwZT0-MTYsIDp3aW5kb3c9PjxJbnN0YWNhcnQ6OkN1c3RvbWVyczo6QXZhaWxhYmlsaXR5OjpWMTo6VGltZXN0YW1wV2luZG93OiBzdGFydHNfYXQ6IDxHb29nbGU6OlByb3RvYnVmOjpUaW1lc3RhbXA6IHNlY29uZHM6IDE1MTkyNjQ4MDAsIG5hbm9zOiAwPiwgZW5kc19hdDogPEdvb2dsZTo6UHJvdG9idWY6OlRpbWVzdGFtcDogc2Vjb25kczogMTUxOTI3MjAwMCwgbmFub3M6IDA-Pn0=",
      "date": "2018-02-21",
      "window": {
        "start_at": "2018-02-22T02:00:00Z",
        "end_at": "2018-02-22T04:00:00Z",
        "type": "eta",
        "asap": false
      },
      "availability": {
        "available": true,
        "reasons": [],
        "item_codes": []
      }
    }
  ],
  "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"}
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"}
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"}
400Invalid location code"Specified store is not available for pickup."1001{"key":"location_code"}
400Missing location code"can't be blank"1001{"key":"location_code"}
400Invalid items"1 item not found."2000{"upcs":["123"],"items":[{"item_upc":"123"}],"error_name":"ItemNotFoundError"}
403User Not Active"User Not Active"nullNot applicable
404Resource not found"Resource not found"4000Not applicable
Last updated on