Find stores offering last mile delivery
POST /v2/fulfillment/stores/last_mile
Returns an array of stores that offer delivery for the customer's location. The list of stores is sorted by distance, with the store closest to the customer displayed first.
A store is eligible for delivery orders when the pickup_only
flag is set to false
.
By default, shoppers deliver to addresses that are within 30 minutes of the store location. If long distance delivery is enabled for a store, deliveries can be made to addresses that are between 30 and 60 minutes away. When a store offers this option, the long_distance_delivery
flag is set to true
. For more information about enabling this option, see Service areas for delivery.
The find stores operation doesn't check whether the customer's address meets Instacart's deliverability requirements. For example, deliveries to post office boxes are not supported. However, if find_by
contains the address_line_2
field and its value is P.O. Box 123
, one or more stores[]
objects might still be returned.
To determine whether an address is eligible to receive deliveries, you can use the Validate user address or List time slots for last mile delivery operation.
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.
The ability to look up stores by postal code only is deprecated. To guarantee deliverability, a full address is required.
Security
Name | In | Description |
---|---|---|
Authorization | header | The Authorization header with the bearer token acquired during authentication. |
Parameters
None.Request
Field | Type | Required | Description |
---|---|---|---|
find_by | Find_by | ![]() | The location to use for finding the stores. |
Find_by Object
One of the following:
Field | Type | Required | Description |
---|---|---|---|
latitude | number | ![]() | The latitude coordinate. |
longitude | number | ![]() | The longitude coordinate. |
or
Field | Type | Required | Description |
---|---|---|---|
address_line_1 | string | ![]() | The first address line. |
address_line_2 | string | ![]() | The second address line. |
address_type | string | ![]() | The type of address, e.g., "residential". |
postal_code | string | ![]() | The postal/zip code of the address. |
city | string | ![]() | The city or town of the address, e.g., "Chicago". |
or
Field | Type | Required | Description |
---|---|---|---|
postal_code | string | ![]() | A zip code or postal code can have numbers and uppercase letters only. Omit spaces. For example: "90210" or "M6K3L5". |
Request examples
- cURL
- Java
- Python
- Go
curl --request POST \
--url https://connect.instacart.com/v2/fulfillment/stores/last_mile \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"find_by": {
"latitude": 1,
"longitude": 1
}
}'
HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/stores/last_mile")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.header("Authorization", "Bearer <token>")
.body("{\n \"find_by\": {\n \"latitude\": 1,\n \"longitude\": 1\n }\n}")
.asString();
import http.client
conn = http.client.HTTPSConnection("connect.instacart.com")
payload = "{\n \"find_by\": {\n \"latitude\": 1,\n \"longitude\": 1\n }\n}"
headers = {
'Accept': "application/json",
'Content-Type': "application/json",
'Authorization': "Bearer <token>"
}
conn.request("POST", "/v2/fulfillment/stores/last_mile", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://connect.instacart.com/v2/fulfillment/stores/last_mile"
payload := strings.NewReader("{\n \"find_by\": {\n \"latitude\": 1,\n \"longitude\": 1\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Accept", "application/json")
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
Response
Field | Type | Required | Description |
---|---|---|---|
stores | Array(Store) | ![]() | The returned stores. |
is_partial | boolean | ![]() | Whether the zip code or postal code has partial coverage. |
Store Object
Field | Type | Required | Description |
---|---|---|---|
name | string | ![]() | The name of the store. |
location_code | string | ![]() | The store code, which is used in other requests to identify the store. |
flags | Flags | ![]() | Properties of the store. |
Flags Object
Field | Type | Required | Description |
---|---|---|---|
alcohol | boolean | ![]() | Whether the store supports alcoholic orders. |
pickup | boolean | ![]() | Whether 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_only | boolean | ![]() | When 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_delivery | boolean | ![]() | Whether a delivery from the store will be a long distance delivery. |
Response examples
200 Success
200
Stores found by address200
Stores found by coordinates
{
"stores": [
{
"name": "Test Warehouse Location 564",
"location_code": "000-33570",
"flags": {
"alcohol": false,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": false
}
},
{
"name": "Test Warehouse Location 565",
"location_code": "000-33585",
"flags": {
"alcohol": true,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": true
}
}
],
"is_partial": false
}
{
"stores": [
{
"name": "Test Warehouse Location 567",
"location_code": "000-33601",
"flags": {
"alcohol": false,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": false
}
},
{
"name": "Test Warehouse Location 568",
"location_code": "000-33616",
"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 Code | Cause | Error Message | Error Code | Error Meta |
---|---|---|---|---|
400 | No stores found | "Stores not found for the provided request." | 1001 | Not applicable |
400 | Postal code not found | "Postal code not found." | 1001 | {"key":"postal_code"} |
400 | Malformed find_by object | "value is not valid" | 1001 | {"key":"find_by"} |
400 | Missing both postal code and coordinates | "can't be blank" | 1001 | {"key":"find_by"} |