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

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

Java

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();

Python

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"))

Go

package main

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

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, _ := ioutil.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.
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	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.

Error Object

Field	Type	Required	Description
error	ErrorDetails		Information relevant to the error.
meta	MetaError		The error metadata.

ErrorDetails Object

Field	Type	Required	Description
message	string		The error message.
error_code	integer		The error code.

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	Required	Description
line_num	string		The item's line number in the order.
qty	number		The quantity of the item.
qty_unit	string		The quantity type, either "each" or "lb".
qty_fulfilled	number		The fulfilled quantity of the item.
qty_fulfilled_unit	string		The fulfilled quantity type, either "each" or "lb".
qty_requested	number		The initally requested quantity of the item.
qty_requested_unit	string		The initally requested quantity type, either "each" or "lb".
replaced	boolean		Indicates whether the item was replaced.
scan_code	string		The scan code of the item.
replacement_policy	string		The replacement policy for the item.
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	Required	Description
upc	string		The item's universal product code (UPC).
rrc	string		The item's retailer reference code (RRC).
requested_upc	string		The requested item's universal product code (UPC).
requested_rrc	string		The requested item's retailer reference code (RRC).
delivered_upc	string		The delivered item's universal product code (UPC).
delivered_rrc	string		The delivered item's retailer reference code (RRC).

Response examples

200 Success

200 Order found

{
  "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": {
    "store_location": "000-32504",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z",
    "bag_count": 3
  },
  "items": [
    {
      "line_num": "77",
      "qty": 5,
      "qty_unit": "each",
      "qty_fulfilled": 25,
      "qty_fulfilled_unit": "lb",
      "qty_requested": 20,
      "qty_requested_unit": "lb",
      "replaced": false,
      "scan_code": "00070481001190",
      "replacement_policy": "shoppers_choice",
      "item": {
        "upc": "987665788999",
        "rrc": "0452-38492",
        "requested_upc": "123456789012",
        "requested_rrc": "0382-85739",
        "delivered_upc": "987665788999",
        "delivered_rrc": "0452-38492"
      }
    }
  ],
  "pos_payment_method": "UNSPECIFIED"
}

200 With replaced items

{
  "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": {
    "store_location": "000-32450",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "72",
      "qty": 8,
      "qty_unit": "each",
      "qty_fulfilled": 25,
      "qty_fulfilled_unit": "lb",
      "qty_requested": 20,
      "qty_requested_unit": "lb",
      "replaced": false,
      "scan_code": "00070481001185",
      "replacement_policy": "shoppers_choice",
      "item": {
        "upc": "replacement_upc",
        "rrc": "",
        "requested_upc": "requested_upc",
        "requested_rrc": "",
        "delivered_upc": "replacement_upc",
        "delivered_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