Skip to main content

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​

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

Parameters​

NameInTypeRequiredDescription
user_idpathstringRequired

The ID of the user.

order_idpathstringRequired

The ID of the order.

Request​

FieldTypeRequiredDescription
service_option_hold_idintegerOptional

The ID of the service option hold.

initial_tip_centsintegerRequired

The pre-delivery tip amount in cents.

special_instructionsstringOptional

Special instructions about the order to pass on to the shopper.

metadataHashOptional

The order-level metadata.

userOrderUserOptional

Any additional attributes for the user, these take precedence over values set during user create.

itemsArray(OrderItem)Required

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​

FieldTypeRequiredDescription
birthdaystringOptional

The user's birthday in ISO 8601 format, this is used for alcohol eligibility validation.

phone_numberstringOptional

The user's phone number.

sms_opt_inbooleanOptional

Indicator whether the user has opted-in to receive SMS communications.

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequired

The item's line number in the order.

countintegerOptional

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.

weightnumberOptional

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_instructionsstringOptional

Any special instructions about the item selection.

replacement_policystringOptional

One of "no_replacements", "users_choice" (default if replacement_items specified), or "shoppers_choice" (default otherwise).

metadataHashOptional

The item-level metadata.

replacement_itemsArray(Replacement_items)Optional

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.

itemItemRequired

The item's code.

Replacement_items Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

Item Object​

One of the following:

FieldTypeRequiredDescription
upcstringRequired

The item's universal product code (upc).

or

FieldTypeRequiredDescription
rrcstringRequired

The item's retailer reference code (rrc).

Request examples​

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

Response​

FieldTypeRequiredDescription
idstringRequired

The retailer-generated order ID.

statusstringRequired

The current status of the order.

order_urlstringOptional

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_atstringOptional

The time of order creation in ISO 8601 format.

cancellation_reasonstringOptional

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.

localestringOptional

Indicates how the order is localized.

is_expressbooleanOptional

Deprecated. Use is_instacartplus instead. Indicates whether the order received Instacart+ membership benefits. Defaults to false.

is_instacartplusbooleanOptional

Indicates whether the order received Instacart+ membership benefits. Defaults to false.

metadataHashOptional

The order-level metadata.

fulfillment_detailsOrderFulfillmentDetailsOptional

The order's fulfillment details.

warningsArray(Error)Optional

Any warnings associated with this request.

itemsArray(OrderItem)Optional

The items in the order.

OrderFulfillmentDetails Object​

FieldTypeRequiredDescription
store_locationstringOptional

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_atstringRequired

The start of the fulfillment window in ISO 8601 format.

window_ends_atstringRequired

The end of the fulfillment window in ISO 8601 format.

delivered_atstringOptional

The time the order was delivered to the customer in ISO 8601 format. Only present for completed deliveries.

bag_countintegerOptional

The number of bags in the order, as reported by the shopper.

handoff_window_starts_atstringOptional

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_atstringOptional

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​

FieldTypeRequiredDescription
errorErrorDetailsOptional

Information relevant to the error.

metaMetaErrorOptional

The error metadata.

ErrorDetails Object​

FieldTypeRequiredDescription
messagestringOptional

The error message.

error_codeintegerOptional

The error code.

MetaError Object​

FieldTypeRequiredDescription
itemsArray(ItemInfo)Optional

The items that triggered the error.

ItemInfo Object​

FieldTypeRequiredDescription
item_codestringOptional

The retailer reference code (RRC) or universal product code (UPC) of an item that triggered the error.

OrderItem Object​

FieldTypeRequiredDescription
line_numstringRequired

The item's line number as provided by the retailer in the create order request.

qtynumberOptional

The quantity of the item. For unpicked items, this is the ordered quantity. For picked items, this is the delivered quantity.

qty_unitstringOptional

The unit of measure for the quantity. Either each for count-based items or lb for weight-based items.

qty_fulfillednumberOptional

The fulfilled quantity of the item (the actual quantity picked and delivered).

qty_fulfilled_unitstringOptional

The unit of measure for the fulfilled quantity. Either each for count-based items or lb for weight-based items.

qty_requestednumberOptional

The initially requested quantity of the item (what the customer originally ordered).

qty_requested_unitstringOptional

The unit of measure for the initially requested quantity. Either each for count-based items or lb for weight-based items.

replacedbooleanOptional

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_codestringOptional

The barcode or scan code that the shopper scanned when picking this item.

replacement_policystringOptional

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_namestringOptional

The item name provided by shoppers for items that they added.

metadataHashOptional

The item-level metadata.

shopper_provided_item_priceMoneyOptional

The item price provided by shoppers for items that they added.

itemItemRequired

The item's codes.

Money Object​

FieldTypeRequiredDescription
amountnumberRequired

The amount of a specified currency.

currencystringRequired

The currency type in ISO 4217 format. For example: USD.

Item Object​

FieldTypeRequiredDescription
upcstringOptional

The item's universal product code (UPC). For unpicked items, this is the requested UPC. For picked items, this is the delivered UPC.

rrcstringOptional

The item's retailer reference code (RRC). For unpicked items, this is the requested RRC. For picked items, this is the delivered RRC.

requested_upcstringOptional

The UPC of the item that the customer originally requested to purchase.

requested_rrcstringOptional

The RRC of the item that the customer originally requested to purchase.

delivered_upcstringOptional

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_rrcstringOptional

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

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

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Invalid user id"User Not Found"1001{"key":"user_id"}
400User and order without phone number"can't be blank"1001{"key":"user.phone_number"}
400Invalid replacement_policy"is not included in the list"1001{"key":"items[0].replacement_policy"}
400Invalid items"1 item not found."2000{"items":[{"item_upc":"123456789101"}]}
400Deleted 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."4001Not applicable
400Invalid 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"}
400Invalid 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"}
400Invalid order params*"There were issues with your request"9999Not applicable
400Tip over maximum"Tip value is above maximum: $300.00."1001{"key":"initial_tip_cents"}
400Fails alcohol compliance check"Alcoholic items can not be added to this order. Please remove and retry."2001Not applicable
400Too 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"}]}
400Invalid zip code for alcohol"Cannot deliver alcohol to this zip code."1001{"key":"zip_code","items":[{"item_upc":"123456789"}]}
400Order updated recently"Order has been recently updated, please try again in a little while."2003{"wait":1200,"retry":true}
400Too late to update order"The order can no longer be updated."2020Not applicable
400Invalid replacement items provided"An item cannot be replaced by itself."1020{"items":[{"item_rrc":"123456789999"},{"item_rrc":"000078671563"}]}
400Service option is no longer available"The delivery time you selected is no longer available - please select another time"1001{"key":"service_option_id"}
400Expired ETA option hold"ETA option hold has expired."1001{"key":"service_option_hold_id"}
400Too 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."2023Not applicable
400Too 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."2026Not applicable
400Too 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."2024Not applicable
400Too 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."2027Not applicable
400Alcohol 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"}]}
400Duplicate 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"}]}
400Duplicate line nums"Duplicate line_num values not allowed: 123,345"2006{"duplicate_line_nums":["123","345"]}
400Age requirement otc medicine"You must be over 18 to purchase over the counter medicine in your cart."1001{"items":[{"item_upc":"12345"}]}
400User birthday missing or invalid for alcohol order"Required parameter missing or invalid"1001{"key":"user_birthday","items":[{"item_upc":"alcohol_upc"}]}
400Retry later"The request could not be completed at this time, try again later."1001{"wait":30}
403Inactive user"User Not Active"nullNot applicable
* Multiple error
Last updated on