Update a last mile delivery order

PUT /v2/fulfillment/users/{user_id}/orders/{order_id}/last_mile

Updates a last mile delivery order.

To successfully perform this operation, the order's status value must be brand_new. In other words, once a shopper is assigned and status moves to acknowledged, you can no longer use this endpoint to update the order.

You can change the delivery window, order details, and the pre-delivery tip amount.

When changing the delivery window, the start and end timestamps must fall within the window specified in the selected service option (time slot). If the timestamps are outside the window, the request fails. To select a new service option, list the available service options and select one. You don’t need to reserve it. Copy the values for the service option id, start_at, and end_at fields, and put these values in the request's service_option_id, start_at, and end_at fields.

note

If the original order was created with leave_unattended set to true and alcohol is added in the update order request, the leave_unattended parameter is changed to false automatically. If all alcohol is later removed, the parameter is not changed and remains false.

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.
order_id	path	string		The ID of the order.

Request

Field	Type	Required	Description
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_id	integer		The ID of the service option for the order.
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.
alcoholic	boolean		Indicates whether the order contains alcohol.
bag_label	string		A user-friendly label that helps shoppers identify the order.
special_instructions	string		Special instructions about the order to pass on to the shopper.

info

When you update the delivery window, service_option_id, start_at, and end_at are required fields.

Request examples

cURL

curl --request PUT \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/last_mile' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start_at": "string",
  "end_at": "string",
  "service_option_id": 1,
  "initial_tip_cents": 1,
  "items_count": 1,
  "bags_count": 1,
  "items_weight": 1,
  "cart_total": 1,
  "alcoholic": true,
  "bag_label": "string",
  "special_instructions": "string"
}'

Java

HttpResponse<String> response = Unirest.put("https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/last_mile")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"start_at\": \"string\",\n  \"end_at\": \"string\",\n  \"service_option_id\": 1,\n  \"initial_tip_cents\": 1,\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"cart_total\": 1,\n  \"alcoholic\": true,\n  \"bag_label\": \"string\",\n  \"special_instructions\": \"string\"\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"start_at\": \"string\",\n  \"end_at\": \"string\",\n  \"service_option_id\": 1,\n  \"initial_tip_cents\": 1,\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"cart_total\": 1,\n  \"alcoholic\": true,\n  \"bag_label\": \"string\",\n  \"special_instructions\": \"string\"\n}"

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

conn.request("PUT", "/v2/fulfillment/users/{user_id}/orders/{order_id}/last_mile", 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/users/{user_id}/orders/{order_id}/last_mile"

	payload := strings.NewReader("{\n  \"start_at\": \"string\",\n  \"end_at\": \"string\",\n  \"service_option_id\": 1,\n  \"initial_tip_cents\": 1,\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"cart_total\": 1,\n  \"alcoholic\": true,\n  \"bag_label\": \"string\",\n  \"special_instructions\": \"string\"\n}")

	req, _ := http.NewRequest("PUT", 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 updated

{
  "id": "12345676789012345678780",
  "status": "created",
  "order_url": "https://example.com/example-order",
  "created_at": "2018-02-22T00:00:00Z",
  "cancellation_reason": "shopper_driven",
  "locale": "en_US",
  "is_express": true,
  "is_instacartplus": true,
  "fulfillment_details": {
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-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	User Not Found	"User Not Found"	1001	{"key":"user_id"}
400	Invalid order params	"Invalid service option id."	1001	{"key":"order.service_option_id"}
400	Fails alcohol compliance check	"Alcoholic items can not be added to this order. Please remove and retry."	2001	Not applicable
400	Order updated recently	"Order has been recently updated, please try again in a little while."	2003	{"wait":1200,"retry":true}
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	Request could not be processed at this time	"The request could not be completed at this time, try again later."	2003	{"wait":"30"}
403	User Not Active	"User Not Active"	null	Not applicable
404	Resource not found	"Resource not found"	4000	Not applicable