Find stores offering last mile delivery
POST /v2/fulfillment/stores/last_mile
This operation lets you to find stores that offer last mile deliveries (LMD) to the customer’s location. In your request, the location can be represented as geographical coordinates, an address, or simply a postal code.
Instacart recommends not searching for stores by postal code alone because the results might not always be accurate.
If you search for stores by address, the operation doesn’t verify whether the address meets all Instacart’s serviceability requirements. For example, even though we don’t deliver to post office boxes, assigning P.O. Box 123
to address_type
might still return one or more stores[]
.
To determine whether an address is serviceable before creating an order, use the Validate user address or List time slots for LMD operations.
The stores[]
in the response are sorted by their distance to the customer’s location, from nearest to farthest.
Each store has a set of flags
. If a store’s pickup_only
flag is true
, then it doesn’t offer LMD. If a store allows alcohol deliveries, then its alcohol
flag is true
. For more information, see Alcohol compliance.
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.
After you select a store, save its location_code
because it is a required field in the create LMD order request.
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 available stores, sorted by distance to the customer’s location, from nearest to farthest. |
is_partial | boolean | ![]() | Indicates whether the requested postal_code has partial or full coverage. If true, then some addresses in the postal_code are outside one or more of the store’s delivery areas. Therefore, delivery coverage isn’t guaranteed for all addresses. If false, then every address in the postal_code is within all of the store’s delivery areas. |
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 600",
"location_code": "000-33865",
"flags": {
"alcohol": false,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": false
}
},
{
"name": "Test Warehouse Location 601",
"location_code": "000-33873",
"flags": {
"alcohol": true,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": true
}
}
],
"is_partial": false
}
{
"stores": [
{
"name": "Test Warehouse Location 603",
"location_code": "000-33896",
"flags": {
"alcohol": false,
"pickup": true,
"pickup_only": false,
"long_distance_delivery": false
}
},
{
"name": "Test Warehouse Location 604",
"location_code": "000-33904",
"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"} |