Find stores offering last mile delivery

POST /v2/fulfillment/lastmile/stores

Deprecated

For last mile delivery implementations, this endpoint has been replaced by Find stores offering last mile delivery. The URI has changed, but the request parameters and responses remain the same. The new URI is consistent in format with the delivery and pickup workflows. This change reflects our commitment to making our API more intuitive to use when implementing multiple fulfillment workflows in your e-commerce site. The deprecated endpoint is still supported for existing implementations. For new implementations, use the revised endpoint.

For dispatch last mile delivery implementations, this endpoint has been restored. The URI, request parameters, and responses remain the same. Use the Find stores offering dispatch last mile delivery endpoint instead.

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.

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.

warning

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

Name	In	Description
`Authorization`	header	The Authorization header with the bearer token acquired during authentication.

Parameters

Name	In	Description
`Authorization`	header	The Authorization header with the bearer token acquired during authentication.

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.

Field	Type	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".

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/lastmile/stores \
  --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/lastmile/stores")
  .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/lastmile/stores", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://connect.instacart.com/v2/fulfillment/lastmile/stores"

	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, _ := io.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	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	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.
`rx_eligible`	boolean	Whether the store is eligible for RX orders.

Response examples

200 Success

200 Stores found by address
200 Stores found by coordinates

{
  "stores": [
    {
      "name": "Test Warehouse Location 647",
      "location_code": "000-34145",
      "flags": {
        "alcohol": false,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": false
      }
    },
    {
      "name": "Test Warehouse Location 648",
      "location_code": "000-34153",
      "flags": {
        "alcohol": true,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": true
      }
    }
  ],
  "is_partial": false
}

{
  "stores": [
    {
      "name": "Test Warehouse Location 650",
      "location_code": "000-34176",
      "flags": {
        "alcohol": false,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": false
      }
    },
    {
      "name": "Test Warehouse Location 651",
      "location_code": "000-34184",
      "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`	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"}`
`400`	Postal code not found	"Postal code not found."	`1001`	`{"key":"postal_code"}`

Security​

Parameters​

Request​

Find_by Object​

Request examples​

Response​

Store Object​

Flags Object​

Response examples​