Skip to main content

Update a last mile delivery order

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

Updates a last mile delivery order. You can change the delivery window, order details, and the pre-delivery tip amount.

info

After an order is assigned for fulfillment, you cannot update the order.

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

NameInDescription
AuthorizationheaderThe Authorization header with the bearer token acquired during authentication.

Parameters

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.
order_idpathstringRequiredThe ID of the order.

Request

FieldTypeRequiredDescription
start_atstringOptionalThe requested delivery window start time in ISO 8601 format.
end_atstringOptionalThe requested delivery window end time in ISO 8601 format.
service_option_idintegerOptionalThe ID of the service option for the order.
initial_tip_centsintegerOptionalThe pre-delivery tip in cents.
items_countintegerOptionalThe number of items in the order.
bags_countintegerOptionalThe number of bags in the order.
items_weightnumberOptionalThe weight of the items in lbs.
cart_totalnumberOptionalThe gross merchandise value (gmv) of the cart.
alcoholicbooleanOptionalIndicates whether the order contains alcohol.
bag_labelstringOptionalA user-friendly label that helps shoppers identify the order.
special_instructionsstringOptionalSpecial 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 --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"
}'

Response

FieldTypeRequiredDescription
idstringRequiredThe ID of the order.
statusstringRequiredThe current order status.
order_urlstringOptionalLink to view the order.
created_atstringOptionalThe time of order creation in ISO 8601 format.
cancellation_reasonstringOptionalThe reason the order was canceled.
localestringOptionalThe order's locale in POSIX format. Example: en_US.
is_expressbooleanOptionalDeprecated. Use `is_instacartplus` instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.
is_instacartplusbooleanOptionalIndicates whether the order received Instacart+ membership benefits. Defaults to false.
fulfillment_detailsOrderFulfillmentDetailsOptionalThe order delivery details.

OrderFulfillmentDetails Object

FieldTypeRequiredDescription
store_locationstringOptionalThe 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_atstringRequiredThe start time of the delivery window in ISO 8601 format.
window_ends_atstringRequiredThe end time of the delivery window in ISO 8601 format.
delivered_atstringOptionalThe time the order was delivered in ISO 8601 format.
bag_countintegerOptionalThe number of bags in the order.
handoff_window_starts_atstringOptionalThe start time of the handoff window in ISO 8601 format.
handoff_window_ends_atstringOptionalThe end time of the handoff window in ISO 8601 format.

Response examples

200 Success

{
"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 CodeCauseError MessageError CodeError Meta
400User Not Found"User Not Found"1001{"key":"user_id"}
400Invalid order params"Invalid service option id."1001{"key":"order.service_option_id"}
400Fails alcohol compliance check"Alcoholic items can not be added to this order. Please remove and retry."2001Not applicable
400Order updated recently"Order has been recently updated, please try again in a little while."2003{"wait":1200,"retry":true}
403User Not Active"User Not Active"nullNot applicable