Update an order

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

Updates a delivery or pickup order.

To successfully perform this operation, the order's status value must be brand_new. In other words, once a shopper is assigned and status moves to acknowledged, you can no longer use this endpoint to update the order.

You can change the time slot, tip amount, instructions, user details, and items.

Order item modifications

To add an object to the items[] array, assign it a line_num value unique to that order. If you provide the line_num of an existing or a deleted item, then Instacart updates and returns that object.

For example, consider an order that already has an item with a line_num of 1 and an item.upc value of abc. If you attempt to update that order, and your request contains an object in items[] with the same line_num and a item.upc of xyz, then Instacart uses the line_num in the request to look up the object with an item.upc of abc and makes the requested updates to it.

To update an existing object in items[], re-use its line_num. If you assign the object that you want to update a new line_num, then Instacart returns a duplicate items error.

To remove an existing object from items[], omit it from the request. If you add another item object in a subsequent update request, don't assign it the line_num of the deleted object because doing so restores it to the order.

Order item limitations

If your request specifies a delivery order containing items that exceed any of the following limitations, the order is not updated:

• Maximum total quantity of items
• Maximum total weight of beverage items
• Maximum quantity of large or bulky items

For more information about why a delivery order couldn't be updated, see the returned error message.

Unattended delivery and alcohol

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

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 ID of the order.

Request

Field	Type	Required	Description
service_option_hold_id	integer		The ID of the service option hold.
initial_tip_cents	integer		The pre-delivery tip amount in cents.
special_instructions	string		Special instructions about the order to pass on to the shopper.
metadata	Hash		The order-level metadata.
user	OrderUser		Any additional attributes for the user, these take precedence over values set during user create.
items	Array(OrderItem)		The items for the order. Existing order items will be looked up by their line numbers and updated, and those that are not specified in the request will be removed. Only count, weight, special instructions and replacement items can be updated.

OrderUser Object

Field	Type	Required	Description
birthday	string		The user's birthday in ISO 8601 format, this is used for alcohol eligibility validation.
phone_number	string		The user's phone number.
sms_opt_in	boolean		Indicator whether the user has opted-in to receive SMS communications.

OrderItem Object

Field	Type	Required	Description
line_num	string		The item's line number in the order.
count	integer		The count of the item. Must be a non-negative integer. Depending on the item's catalog configuration, either this field or 'weight' is required.
weight	number		For items sold by weight, the numerical weight of the item. Depending on the item's catalog configuration, either this field or 'count' is required. The API interprets this value as whatever unit of measure is defined for the item in the catalog, such as lb or kg. Must be a non-negative number.
special_instructions	string		Any special instructions about the item selection.
replacement_policy	string		One of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).
metadata	Hash		The item-level metadata.
replacement_items	Array(Replacement_items)		A list of requested replacement items if the original item could not be found. This field needs to be turned on via configuration. Contact your Instacart Connect representative.
item	Item		The item's code.

Replacement_items Object

One of the following:

Field	Type	Required	Description
upc	string		The item's universal product code (upc).

or

Field	Type	Required	Description
rrc	string		The item's retailer reference code (rrc).

Item Object

One of the following:

Field	Type	Required	Description
upc	string		The item's universal product code (upc).

or

Field	Type	Required	Description
rrc	string		The item's retailer reference code (rrc).

Request examples

cURL

curl --request PUT \
  --url 'https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "service_option_hold_id": 1,
  "initial_tip_cents": 1,
  "special_instructions": "string",
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  },
  "user": {
    "birthday": "string",
    "phone_number": "string",
    "sms_opt_in": true
  },
  "items": [
    {
      "line_num": "string",
      "count": 1,
      "weight": 1,
      "special_instructions": "string",
      "replacement_policy": "no_replacements",
      "metadata": {
        "key1": "value1",
        "key2": "value2"
      },
      "replacement_items": [
        {
          "upc": "string"
        }
      ],
      "item": {
        "upc": "string"
      }
    }
  ]
}'

Java

HttpResponse<String> response = Unirest.put("https://connect.instacart.com/v2/fulfillment/users/{user_id}/orders/{order_id}")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"service_option_hold_id\": 1,\n  \"initial_tip_cents\": 1,\n  \"special_instructions\": \"string\",\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"user\": {\n    \"birthday\": \"string\",\n    \"phone_number\": \"string\",\n    \"sms_opt_in\": true\n  },\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"count\": 1,\n      \"weight\": 1,\n      \"special_instructions\": \"string\",\n      \"replacement_policy\": \"no_replacements\",\n      \"metadata\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\"\n      },\n      \"replacement_items\": [\n        {\n          \"upc\": \"string\"\n        }\n      ],\n      \"item\": {\n        \"upc\": \"string\"\n      }\n    }\n  ]\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"service_option_hold_id\": 1,\n  \"initial_tip_cents\": 1,\n  \"special_instructions\": \"string\",\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"user\": {\n    \"birthday\": \"string\",\n    \"phone_number\": \"string\",\n    \"sms_opt_in\": true\n  },\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"count\": 1,\n      \"weight\": 1,\n      \"special_instructions\": \"string\",\n      \"replacement_policy\": \"no_replacements\",\n      \"metadata\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\"\n      },\n      \"replacement_items\": [\n        {\n          \"upc\": \"string\"\n        }\n      ],\n      \"item\": {\n        \"upc\": \"string\"\n      }\n    }\n  ]\n}"

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

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

	payload := strings.NewReader("{\n  \"service_option_hold_id\": 1,\n  \"initial_tip_cents\": 1,\n  \"special_instructions\": \"string\",\n  \"metadata\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  },\n  \"user\": {\n    \"birthday\": \"string\",\n    \"phone_number\": \"string\",\n    \"sms_opt_in\": true\n  },\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"count\": 1,\n      \"weight\": 1,\n      \"special_instructions\": \"string\",\n      \"replacement_policy\": \"no_replacements\",\n      \"metadata\": {\n        \"key1\": \"value1\",\n        \"key2\": \"value2\"\n      },\n      \"replacement_items\": [\n        {\n          \"upc\": \"string\"\n        }\n      ],\n      \"item\": {\n        \"upc\": \"string\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("PUT", 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.
warnings	Array(Error)		Any warnings associated with this request.
items	Array(OrderItem)		The items in the order.

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 updated

{
  "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-32566",
    "window_starts_at": "2018-02-22T00:00:00Z",
    "window_ends_at": "2018-02-22T00:30:00Z"
  },
  "items": [
    {
      "line_num": "82",
      "qty": 6,
      "qty_unit": "each",
      "replaced": false,
      "scan_code": "00070481001197",
      "replacement_policy": "shoppers_choice",
      "rx": false,
      "item": {
        "upc": "123456789094",
        "rrc": "",
        "requested_upc": "123456789094",
        "requested_rrc": "",
        "delivered_upc": "123456789094",
        "delivered_rrc": ""
      }
    }
  ]
}

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"}
400	User and order without phone number	"can't be blank"	1001	{"key":"user.phone_number"}
400	Invalid replacement_policy	"is not included in the list"	1001	{"key":"items[0].replacement_policy"}
400	Invalid items	"1 item not found."	2000	{"items":[{"item_upc":"123456789103"}]}
400	Deleted item exists for new item	"A deleted item exists for a new item being added to this order. Please adjust quantity for the deleted item instead of adding a new item."	4001	Not applicable
400	Invalid Quantity, expected count	"One of these items had an invalid quantity amount, some_upc expected count"	2012	{"upc":"some_upc","item_code":"some_upc","expected_param":"count"}
400	Invalid Quantity, expected weight	"One of these items had an invalid quantity amount, some_upc expected weight"	2012	{"upc":"some_upc","item_code":"some_upc","expected_param":"weight"}
400	Invalid order params*	"There were issues with your request"	9999	Not applicable
400	Tip over maximum	"Tip value is above maximum: $300.00."	1001	{"key":"initial_tip_cents"}
400	Fails alcohol compliance check	"Alcoholic items can not be added to this order. Please remove and retry."	2001	Not applicable
400	Too much alcohol	"State law restricts the amount of wine and beer we can deliver in a single order. Please remove 253716 fl oz wine and 80 fl oz beer from your cart to continue."	2001	{"upcs":["alcohol_upc_1","alcohol_upc_2"],"items":[{"item_upc":"alcohol_upc_1"},{"item_upc":"alcohol_upc_2"}]}
400	Order updated recently	"Order has been recently updated, please try again in a little while."	2003	{"wait":1200,"retry":true}
400	Too late to update order	"The order can no longer be updated."	2020	Not applicable
400	Invalid replacement items provided	"An item cannot be replaced by itself."	1020	{"items":[{"item_rrc":"123456789999"},{"item_rrc":"000078671563"}]}
400	Service option is no longer available	"The delivery time you selected is no longer available - please select another time"	1001	{"key":"service_option_id"}
400	Expired ETA option hold	"ETA option hold has expired."	1001	{"key":"service_option_hold_id"}
400	Too many big and bulky items	"The number of big and bulky items in your cart exceeds our maximum limit for a single delivery. Please remove 2 such items from your cart to continue."	2023	Not applicable
400	Too much beverage	"The weight of beverages in your cart exceeds our maximum limit for a single delivery. Please remove 20lb of beverages from your cart to continue."	2026	Not applicable
400	Too many items	"The number of items in your cart exceeds our maximum limit for a single delivery. Please remove 15 such items from your cart to continue."	2024	Not applicable
400	Too much weight	"The total weight of items in your cart exceeds our maximum limit for a single delivery. Please remove 20 lb from your cart to continue."	2027	Not applicable
400	Alcohol outside of allowed time window	"State law restricts selling alcohol during the window you selected. Please change your delivery window to add alcohol."	2001	{"upcs":["alcohol_upc"],"items":[{"item_upc":"alcohol_upc"}]}
400	Duplicate items were provided	"Duplicate items provided for this order."	2007	{"duplicate_items":[{"item_upc":"123456789999","item_rrc":null,"line_num":"0"},{"item_upc":"123456789999","item_rrc":null,"line_num":"1"}]}
400	Duplicate line nums	"Duplicate line_num values not allowed: 123,345"	2006	{"duplicate_line_nums":["123","345"]}
400	Age requirement otc medicine	"You must be over 18 to purchase over the counter medicine in your cart."	1001	{"items":[{"item_upc":"12345"}]}
400	User birthday missing or invalid for alcohol order	"Required parameter missing or invalid"	1001	{"key":"user_birthday","items":[{"item_upc":"alcohol_upc"}]}
400	Retry later	"The request could not be completed at this time, try again later."	1001	{"wait":30}
403	Inactive user	"User Not Active"	null	Not applicable

* Multiple error