Skip to main content

Find stores offering dispatch last mile delivery

POST /v2/fulfillment/lastmile/stores

Returns an array of stores that offer delivery for the customer's location. A store is eligible for delivery orders when the pickup_only flag is set to false.

caution

This endpoint works only with dispatch last mile delivery orders.

If a store offers alcohol, the alcohol flag is set to true. For more information see Alcohol compliance.

After a store is selected, save the store location_code. You specify the location when creating an order.

caution

When searching by postal code only, it's possible that a delivery service area covers some but not all of the addresses in the postal code area. Check the response. If the is_partial flag is set to true, send another request with the customer's address_line_1 filled to verify that the address is within the service area. If the response contains the store location, the address is serviceable and you can create an order.

Security

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

Parameters

None.

Request

FieldTypeRequiredDescription
find_byFind_byRequiredThe location to use for finding the stores.

Find_by Object

One of the following:

FieldTypeRequiredDescription
latitudenumberRequiredThe latitude coordinate.
longitudenumberRequiredThe longitude coordinate.

or

FieldTypeRequiredDescription
address_line_1stringRequiredThe first address line.
address_line_2stringOptionalThe second address line.
address_typestringOptionalThe type of address, e.g., "residential".
postal_codestringRequiredThe postal/zip code of the address.
citystringOptionalThe city or town of the address, e.g., "Chicago".

or

FieldTypeRequiredDescription
postal_codestringRequiredA zip code or postal code can have numbers and uppercase letters only. Omit spaces. For example: "90210" or "M6K3L5".

Request examples

curl --request POST \
--url https://connect.instacart.com/v2/fulfillment/lastmile/stores \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"find_by": {
"latitude": 1,
"longitude": 1
}
}'

Response

FieldTypeRequiredDescription
storesArray(Store)OptionalThe returned stores.
is_partialbooleanOptionalWhether the zip code or postal code has partial coverage.

Store Object

FieldTypeRequiredDescription
namestringRequiredThe name of the store.
location_codestringRequiredThe store code, which is used in other requests to identify the store.
flagsFlagsRequiredProperties of the store.

Flags Object

FieldTypeRequiredDescription
alcoholbooleanRequiredWhether the store supports alcoholic orders.
pickupbooleanRequiredWhether the store supports pickup orders. When pickup is true, the store supports both pickup and delivery. When pickup is false, the store supports only delivery orders.
pickup_onlybooleanRequiredWhen the pickup flag is true, the pickup_only value indicates whether the store supports delivery in addition to pickup. When pickup_only is false, the store supports delivery. When pickup_only is true, the store doesn't support delivery.
long_distance_deliverybooleanOptionalWhether a delivery from the store will be a long distance delivery.

Response examples

200 Success

{
"stores": [
{
"name": "Test Warehouse Location 576",
"location_code": "000-33710",
"flags": {
"alcohol": false,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": false
}
},
{
"name": "Test Warehouse Location 577",
"location_code": "000-33725",
"flags": {
"alcohol": true,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": true
}
}
],
"is_partial": false
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400No stores found"Stores not found for the provided request."1001Not applicable
400Malformed find_by object"value is not valid"1001{"key":"find_by"}
400Missing both postal code and coordinates"can't be blank"1001{"key":"find_by"}
400Postal code not found"Postal code not found."1001{"key":"postal_code"}