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.

warning

This endpoint works only with last mile delivery orders.

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 unique ID from the order to be staged.

Request

Field	Type	Required	Description
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.
bag_label	string		A user-friendly label that helps shoppers identify the order.
bag_scan_codes	Array(string)		The array of barcode scan codes that helps shoppers identify the order.

Request examples

cURL

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

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}/staged")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"bag_label\": \"string\",\n  \"bag_scan_codes\": [\n    \"string\"\n  ]\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"bag_label\": \"string\",\n  \"bag_scan_codes\": [\n    \"string\"\n  ]\n}"

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

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

	payload := strings.NewReader("{\n  \"items_count\": 1,\n  \"bags_count\": 1,\n  \"items_weight\": 1,\n  \"bag_label\": \"string\",\n  \"bag_scan_codes\": [\n    \"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 staged

{
  "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"}
403	User Not Active	"User Not Active"	null	Not applicable
404	Order not found	"No order that is eligible to be staged could be found for the provided identifier."	4000	Not applicable