Skip to main content

Stage a last mile delivery order

POST /v2/fulfillment/users/{user_id}/orders/{order_id}/staged

Marks the order as staged and ready for delivery, which triggers an event to dispatch a shopper to the store location. Send this request when the bags are in a staging area. A shopper picks up the order from the staging area, verifies the bag labels to confirm it is the right order, and delivers it.

Optionally, if you generate labels with barcodes to identify last mile delivery orders, you can send those barcodes to Instacart in the stage request. When the shopper arrives to collect an order, the shopper scans the barcodes on the bags to ensure that they have the correct order.

caution

This endpoint works only with last mile delivery orders.

Security

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

Parameters

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.
order_idpathstringRequiredThe unique ID from the order to be staged.

Request

FieldTypeRequiredDescription
items_countintegerOptionalThe number of items in the order.
bags_countintegerOptionalThe number of bags in the order.
items_weightnumberOptionalThe weight of the items in lbs.
bag_labelstringOptionalA user-friendly label that helps shoppers identify the order.
bag_scan_codesArray(string)OptionalThe array of barcode scan codes that helps shoppers identify the order.

Request examples

curl --request POST \
--url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/staged' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"items_count": 1,
"bags_count": 1,
"items_weight": 1,
"bag_label": "string",
"bag_scan_codes": [
"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"}
403User Not Active"User Not Active"nullNot applicable
404Order not found"No order that is eligible to be staged could be found for the provided identifier."4000Not applicable