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

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

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.

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

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
  }
}'

Java

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();

Python

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

Go

package main

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

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, _ := 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 address

{
  "stores": [
    {
      "name": "Test Warehouse Location 549",
      "location_code": "000-33500",
      "flags": {
        "alcohol": false,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": false
      }
    },
    {
      "name": "Test Warehouse Location 550",
      "location_code": "000-33515",
      "flags": {
        "alcohol": true,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": true
      }
    }
  ],
  "is_partial": false
}

200 Stores found by coordinates

{
  "stores": [
    {
      "name": "Test Warehouse Location 552",
      "location_code": "000-33531",
      "flags": {
        "alcohol": false,
        "pickup": true,
        "pickup_only": false,
        "long_distance_delivery": false
      }
    },
    {
      "name": "Test Warehouse Location 553",
      "location_code": "000-33546",
      "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"}