Get an order

GET /v2/fulfillment/users/{user_id}/orders/{order_id}

Retrieves order details by order ID. Order details include the status, creation time, time slot, and the Items object. For orders that have been fulfilled, the response includes the location of the fulfillment store, how many bags were in the order, and when the customer received their order.

Security

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

Parameters

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

Request

None.

Request examples

cURL
Java
Python
Go

curl --request GET \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>'

HttpResponse<String> response = Unirest.get("https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}")
  .header("Accept", "application/json")
  .header("Authorization", "Bearer <token>")
  .asString();

import http.client

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

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

conn.request("GET", "/v2/fulfillment/users/{user_id}/orders/{order_id}", headers=headers)

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

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

package main

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

func main() {

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

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept", "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	Description
`id`	string	The retailer-generated order ID.
`status`	string	The current status of the order.
`order_url`	string	The URL of the Instacart-hosted order status page. If the retailer has opted not to use this feature, this field will be `null` or empty.
`created_at`	string	The time of order creation in ISO 8601 format.
`cancellation_reason`	string	The reason the order was canceled. Only present in canceled orders. One of the following: `customer_driven`: The customer triggered the cancellation `instacart_driven`: Instacart triggered the cancellation `retailer_driven`: The retailer triggered the cancellation `shopper_driven`: The shopper triggered the cancellation `unbatchable`: The Instacart batch system triggered the cancellation `other`: The cancellation was triggered for another reason not listed above.
`locale`	string	Indicates how the order is localized.
`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's fulfillment details.
`warnings`	Array(Error)	Any warnings associated with this request.
`items`	Array(OrderItem)	The items in the order.
`pos_payment_method`	string	The point of sale payment method. The values are UNSPECIFIED (method not set or nil), UNKNOWN (method is not known), MARQETA (Marqeta credit or debit card was used), or BYPASS (custom option was used).

OrderFulfillmentDetails Object

Field	Type	Description
`store_location`	string	The location code of the store where the order was fulfilled. This field's value is often the same as the `location_code` included in the create order request. However, orders can be fulfilled from a store that's different from the one specified by `location_code`.
`window_starts_at`	string	The start of the fulfillment window in ISO 8601 format.
`window_ends_at`	string	The end of the fulfillment window in ISO 8601 format.
`delivered_at`	string	The time the order was delivered to the customer in ISO 8601 format. Only present for completed deliveries.
`bag_count`	integer	The number of bags in the order, as reported by the shopper.
`handoff_window_starts_at`	string	The start of the store-associate-to-Instacart-shopper handoff window in ISO 8601 format. This field is only populated for last mile delivery (i.e., delivery only) orders.
`handoff_window_ends_at`	string	The end of the store-associate-to-Instacart-shopper handoff window in ISO 8601 format. This field is only populated for last mile delivery (i.e., delivery only) orders.

Error Object

Field	Type	Required	Description
`error`	ErrorDetails		The error details.
`meta`	MetaError		Metadata about the error, including the items associated with it.

ErrorDetails Object

Field	Type	Required	Description
`message`	string		A human-readable description of the error.
`error_code`	integer		A numeric code that identifies the error type.

MetaError Object

Field	Type	Required	Description
`items`	Array(ItemInfo)		The items that triggered the error.

ItemInfo Object

Field	Type	Required	Description
`item_code`	string		The retailer reference code (RRC) or universal product code (UPC) of an item that triggered the error.

OrderItem Object

Field	Type	Description
`line_num`	string	The item's line number as provided by the retailer in the create order request.
`qty`	number	The quantity of the item. For unpicked items, this is the ordered quantity. For picked items, this is the delivered quantity.
`qty_unit`	string	The unit of measure for the quantity. Either `each` for count-based items or `lb` for weight-based items.
`qty_fulfilled`	number	The fulfilled quantity of the item (the actual quantity picked and delivered).
`qty_fulfilled_unit`	string	The unit of measure for the fulfilled quantity. Either `each` for count-based items or `lb` for weight-based items.
`qty_requested`	number	The initially requested quantity of the item (what the customer originally ordered).
`qty_requested_unit`	string	The unit of measure for the initially requested quantity. Either `each` for count-based items or `lb` for weight-based items.
`replaced`	boolean	Indicates whether the item was replaced. This is `true` if the item that was picked and delivered differs from the item that was originally requested by the customer.
`scan_code`	string	The barcode or scan code that the shopper scanned when picking this item.
`replacement_policy`	string	The replacement policy for the item. One of the following: `no_replacements`: Do not replace if unavailable. `users_choice`: Replace only with customer-approved alternatives. `shoppers_choice`: Shopper selects best replacement.
`shopper_provided_item_name`	string	The item name provided by shoppers for items that they added.
`metadata`	Hash	The item-level metadata.
`shopper_provided_item_price`	Money	The item price provided by shoppers for items that they added.
`item`	Item	The item's codes.

Money Object

Field	Type	Required	Description
`amount`	number		The amount of a specified currency.
`currency`	string		The currency type in ISO 4217 format. For example: USD.

Item Object

Field	Type	Description
`upc`	string	The item's universal product code (UPC). For unpicked items, this is the requested UPC. For picked items, this is the delivered UPC.
`rrc`	string	The item's retailer reference code (RRC). For unpicked items, this is the requested RRC. For picked items, this is the delivered RRC.
`requested_upc`	string	The UPC of the item that the customer originally requested to purchase.
`requested_rrc`	string	The RRC of the item that the customer originally requested to purchase.
`delivered_upc`	string	The UPC of the item that was actually picked and delivered to the customer. If the item was replaced, this will differ from the `requested_upc`.
`delivered_rrc`	string	The RRC of the item that was actually picked and delivered to the customer. If the item was replaced, this will differ from the `requested_rrc`.

Response examples

200 Success

200 Order found

{
  "id": "aretailerreferenceid",
  "status": "brand_new",
  "order_url": "https://a.b.com/t/x123456",
  "created_at": "2018-02-22T00:00:00Z",
  "cancellation_reason": "other",
  "locale": "",
  "is_express": true,
  "is_instacartplus": true,
  "fulfillment_details": {
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z",
    "bag_count": 2
  },
  "items": [
    {
      "line_num": "1",
      "qty": 20,
      "qty_unit": "lb",
      "qty_fulfilled": 25,
      "qty_fulfilled_unit": "lb",
      "qty_requested": 20,
      "qty_requested_unit": "lb",
      "replaced": false,
      "scan_code": "123456789",
      "replacement_policy": "users_choice",
      "rx": false,
      "item": {
        "upc": "101010",
        "rrc": "some_rrc",
        "requested_upc": "101010",
        "requested_rrc": "some_rrc",
        "delivered_upc": "101010",
        "delivered_rrc": "some_rrc"
      }
    }
  ],
  "pos_payment_method": "UNSPECIFIED"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
`400`	Invalid user id	"User Not Found"	`1001`	`{"key":"user_id"}`
`403`	Inactive user	"User Not Active"	`null`	Not applicable
`404`	Order not found	"Resource not found"	`4000`	Not applicable

Security​

Parameters​

Request​

Request examples​

Response​

OrderFulfillmentDetails Object​

Error Object​

ErrorDetails Object​

MetaError Object​

ItemInfo Object​

OrderItem Object​

Money Object​

Item Object​

Response examples​