Create a last mile delivery order

POST /v2/fulfillment/lastmile/users/{user_id}/orders

Deprecated

This endpoint has been replaced by Create a last mile delivery order. 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.

Creates a last mile delivery order for the reserved time slot. If the reservation has expired, Instacart still attempts to book the time slot. If, however, the time slot capacity is filled, your site needs to prompt the customer to select another time slot.

Security

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

Parameters

Name	In	Type	Required	Description
user_id	path	string		The ID of the user.

Request

Field	Type	Required	Description
order_id	string		The unique retailer-generated order ID to use for the order. The ID can be used later for lookup.
location_code	string		Location code of the store where the delivery driver picks up the order.
locale	string		The order's locale in IETF Language Tag format. Example: en-US.
start_at	string		The requested delivery window start time in ISO 8601 format.
end_at	string		The requested delivery window end time in ISO 8601 format.
service_option_hold_id	integer		The ID of the service option hold.
first_name	string		The user's first name.
last_name	string		The user's last name.
user_phone	string		The user's phone number.
initial_tip_cents	integer		The pre-delivery tip in cents.
items_count	integer		The number of items in the order.
bags_count	integer		The number of bags in the order.
items_weight	number		The weight of the items in lbs.
cart_total	number		The gross merchandise value (gmv) of the cart in dollar amount.
bag_label	string		A user-friendly label that helps shoppers identify the order.
alcoholic	boolean		Indicates whether the order contains alcohol. Defaults to false.
leave_unattended	boolean		Indicates whether the user wants the driver to leave the order unattended. Defaults to false.
special_instructions	string		Special instructions about the order to pass on to the shopper.
customer_sms_opt_out	boolean		Indicator whether the user has opted-out from receiving SMS communication. Defaults to false.
with_handoff_time	boolean		Indicator whether the handoff time is calculated during order creation. Defaults to false.
applied_express	boolean		Deprecated. Use applied_instacartplus instead. Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
applied_instacartplus	boolean		Indicates whether the retailer applied Instacart+ membership benefits to the order. Defaults to false.
address	ExpandedAddress		The address of the user.

ExpandedAddress Object

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

Request examples

cURL

curl --request POST \
  --url 'https://connect.instacart.com/v2/fulfillment/lastmile/users/{user_id}/orders' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "order_id": "string",
  "location_code": "string",
  "locale": "string",
  "start_at": "string",
  "end_at": "string",
  "service_option_hold_id": 1,
  "first_name": "string",
  "last_name": "string",
  "user_phone": "string",
  "initial_tip_cents": 1,
  "items_count": 1,
  "bags_count": 1,
  "items_weight": 1,
  "cart_total": 1,
  "bag_label": "string",
  "alcoholic": true,
  "leave_unattended": true,
  "special_instructions": "string",
  "customer_sms_opt_out": true,
  "with_handoff_time": true,
  "applied_express": true,
  "applied_instacartplus": true,
  "address": {
    "address_line_1": "string",
    "address_line_2": "string",
    "address_type": "string",
    "postal_code": "string",
    "city": "string"
  }
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/lastmile/users/{user_id}/orders")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"order_id\": \"string\",\n  \"location_code\": \"string\",\n  \"locale\": \"string\",\n  \"start_at\": \"string\",\n  \"end_at\": \"string\",\n  \"service_option_hold_id\": 1,\n  \"first_name\": \"string\",\n  \"last_name\": \"string\",\n  \"user_phone\": \"string\",\n  \"initial_tip_cents\": 1,\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"cart_total\": 1,\n  \"bag_label\": \"string\",\n  \"alcoholic\": true,\n  \"leave_unattended\": true,\n  \"special_instructions\": \"string\",\n  \"customer_sms_opt_out\": true,\n  \"with_handoff_time\": true,\n  \"applied_express\": true,\n  \"applied_instacartplus\": true,\n  \"address\": {\n    \"address_line_1\": \"string\",\n    \"address_line_2\": \"string\",\n    \"address_type\": \"string\",\n    \"postal_code\": \"string\",\n    \"city\": \"string\"\n  }\n}")
  .asString();

Python

import http.client

conn = http.client.HTTPSConnection("connect.instacart.com")

payload = "{\n  \"order_id\": \"string\",\n  \"location_code\": \"string\",\n  \"locale\": \"string\",\n  \"start_at\": \"string\",\n  \"end_at\": \"string\",\n  \"service_option_hold_id\": 1,\n  \"first_name\": \"string\",\n  \"last_name\": \"string\",\n  \"user_phone\": \"string\",\n  \"initial_tip_cents\": 1,\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"cart_total\": 1,\n  \"bag_label\": \"string\",\n  \"alcoholic\": true,\n  \"leave_unattended\": true,\n  \"special_instructions\": \"string\",\n  \"customer_sms_opt_out\": true,\n  \"with_handoff_time\": true,\n  \"applied_express\": true,\n  \"applied_instacartplus\": true,\n  \"address\": {\n    \"address_line_1\": \"string\",\n    \"address_line_2\": \"string\",\n    \"address_type\": \"string\",\n    \"postal_code\": \"string\",\n    \"city\": \"string\"\n  }\n}"

headers = {
    'Accept': "application/json",
    'Content-Type': "application/json",
    'Authorization': "Bearer <token>"
}

conn.request("POST", "/v2/fulfillment/lastmile/users/{user_id}/orders", payload, headers)

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

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

Go

package main

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

func main() {

	url := "https://connect.instacart.com/v2/fulfillment/lastmile/users/{user_id}/orders"

	payload := strings.NewReader("{\n  \"order_id\": \"string\",\n  \"location_code\": \"string\",\n  \"locale\": \"string\",\n  \"start_at\": \"string\",\n  \"end_at\": \"string\",\n  \"service_option_hold_id\": 1,\n  \"first_name\": \"string\",\n  \"last_name\": \"string\",\n  \"user_phone\": \"string\",\n  \"initial_tip_cents\": 1,\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"cart_total\": 1,\n  \"bag_label\": \"string\",\n  \"alcoholic\": true,\n  \"leave_unattended\": true,\n  \"special_instructions\": \"string\",\n  \"customer_sms_opt_out\": true,\n  \"with_handoff_time\": true,\n  \"applied_express\": true,\n  \"applied_instacartplus\": true,\n  \"address\": {\n    \"address_line_1\": \"string\",\n    \"address_line_2\": \"string\",\n    \"address_type\": \"string\",\n    \"postal_code\": \"string\",\n    \"city\": \"string\"\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
id	string		The ID of the order.
status	string		The current order status.
order_url	string		Link to view the order.
created_at	string		The time of order creation in ISO 8601 format.
cancellation_reason	string		The reason the order was canceled.
locale	string		The order's locale in POSIX format. Example: en_US.
is_express	boolean		Deprecated. Use is_instacartplus instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.
is_instacartplus	boolean		Indicates whether the order received Instacart+ membership benefits. Defaults to false.
metadata	Hash		The order-level metadata.
fulfillment_details	OrderFulfillmentDetails		The order delivery details.

OrderFulfillmentDetails Object

Field	Type	Required	Description
store_location	string		The location code of the store where the order was fulfilled. The store_location is often the same as the location_code that was used to create the order. However, orders can be fulfilled from a different store location.
window_starts_at	string		The start time of the delivery window in ISO 8601 format.
window_ends_at	string		The end time of the delivery window in ISO 8601 format.
delivered_at	string		The time the order was delivered in ISO 8601 format.
bag_count	integer		The number of bags in the order.
handoff_window_starts_at	string		The start time of the handoff window in ISO 8601 format.
handoff_window_ends_at	string		The end time of the handoff window in ISO 8601 format.

Response examples

200 Success

200 Order created

{
  "id": "12345676789012345678780",
  "status": "created",
  "order_url": "https://example.com/example-order",
  "created_at": "2058-02-22T00:00:00Z",
  "cancellation_reason": "shopper_driven",
  "locale": "en_US",
  "is_express": true,
  "is_instacartplus": true,
  "fulfillment_details": {
    "window_starts_at": "2058-02-22T00:00:00Z",
    "window_ends_at": "2058-02-22T00:30:00Z"
  },
  "handoff_time": "2058-02-22T00:30:00Z",
  "is_fallback_window": false
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Invalid postal code	"not found"	1001	{"key":"postal_code"}
400	Unsupported postal code	"not supported"	1001	{"key":"postal_code"}
400	Store does not support delivery to address	"We do not currently support delivery from this store to the selected address."	1001	{"key":"address"}
400	Handoff time is requested but not configured	"Handoff time calculation is not configured for this retailer."	1001	{"key":"with_handoff_time"}
400	Expired ETA option hold	"ETA option hold has expired."	1001	{"key":"service_option_hold_id"}
400	User without phone number	"can't be blank"	1001	{"key":"user.phone_number"}
400	User with invalid phone number	"Required parameter missing or invalid"	1001	{"key":"user_phone"}
400	Invalid order params*	"There were issues with your request"	9999	Not applicable
400	Fails alcohol compliance check	"Alcoholic items can not be added to this order. Please remove and retry."	2001	Not applicable
400	Order id already exists	"Order already in use."	1003	Not applicable
400	Invalid start at/end at	"Invalid start / end at."	1001	{"key":"order.start_at"}
400	Invalid first name	"First name is invalid"	1001	{"key":"first_name"}
400	Request could not be processed at this time	"The request could not be completed at this time, try again later."	2003	{"wait":"30"}
400	Missing or invalid address	"Required parameter missing or invalid"	1001	{"key":"address"}
400	Invalid address	"invalid_address"	1001	{"key":"address"}
400	Location not available for delivery	"Specified store is not available for delivery."	1001	{"key":"location_code"}
400	Service option is no longer available	"The delivery time you selected is no longer available - please select another time"	1001	{"key":"service_option_id"}
400	Address contains PO box	"address contains PO Box"	1001	{"key":"address"}
400	Invalid service option hold	"Hold not found"	1001	{"key":"service_option_hold_id"}
400	Tip over maximum	"Tip value is above maximum: $300.00."	1002	{"key":"initial_tip_cents"}
400	Another order created recently	"Another order has been recently created for this user, please try again in a little while."	2003	{"wait":10,"retry":true}
403	Inactive user	"User Not Active"	null	Not applicable
404	Order not found	"Resource not found"	4000	Not applicable
423	The target resource is locked	"The target resource is locked."	null	{"key":"order_id"}

* Multiple error