Handle order item replacement

PUT /v2/post_checkout/orders/{order_id}/items/{order_item_id}/replacement

If an Instacart Shopper app user can’t find an order item but proposes a replacement, this operation lets you inform Instacart whether the customer approves of the proposed item. If the customer rejects the proposal, your request can provide an alternative item, which Instacart prompts the shopper to find instead.

In addition to the security, parameter, and request requirements, the following preconditions must be met:

• The order has a workflow_state of picking, which means the shopper is still picking the order items.
• The order item has a status of REPLACED and a replacement_status of PENDING. In other words, the shopper has replaced the order item, but the customer has yet to approve or reject the proposal.

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 order ID.
order_item_id	path	string		The order item ID, which maps to line_items.id in the get order items response.

Request

Field	Type	Required	Description
status	string		Reflects the customer’s decision on the shopper’s proposed replacement item. One of APPROVED or REJECTED. If APPROVED, then alternative_item is not accepted.
alternative_item	Hash		If status is REJECTED, this field lets you provide an alternative to the shopper’s proposed replacement. If provided, the hash must contain exactly one of either upc or rrc and one of either count or weight. The upc represents the item’s Universal Product Code and the rrc represents its Retailer Reference Code. The item’s catalog configuration determines whether count or weight is required. Both must be greater than 0.

Request examples

cURL

curl --request PUT \
  --url 'https://connect.instacart.com/v2/post_checkout/orders/{order_id}/items/{order_item_id}/replacement' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "APPROVED",
  "alternative_item": {
    "key1": "value1",
    "key2": "value2"
  }
}'

Java

HttpResponse<String> response = Unirest.put("https://connect.instacart.com/v2/post_checkout/orders/{order_id}/items/{order_item_id}/replacement")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"status\": \"APPROVED\",\n  \"alternative_item\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  }\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"status\": \"APPROVED\",\n  \"alternative_item\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\n  }\n}"

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

conn.request("PUT", "/v2/post_checkout/orders/{order_id}/items/{order_item_id}/replacement", 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/post_checkout/orders/{order_id}/items/{order_item_id}/replacement"

	payload := strings.NewReader("{\n  \"status\": \"APPROVED\",\n  \"alternative_item\": {\n    \"key1\": \"value1\",\n    \"key2\": \"value2\"\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

None.

Response examples

200 Success

200 Replacement approved

{
 // Empty
}

200 Replacement rejected

{
 // Empty
}

200 Replacement rejected with alternative item (UPC only)

{
 // Empty
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	Cannot provide both rrc and upc	"must include exactly one of rrc or upc"	1001	{"key":"alternative_item"}
400	Cannot provide both count and weight	"must include exactly one of count or weight"	1001	{"key":"alternative_item"}
400	Must provide count or weight	"must include exactly one of count or weight"	1001	{"key":"alternative_item"}
400	Count must be greater than 0	"count must be greater than 0"	1001	{"key":"alternative_item"}
400	Weight must be greater than 0	"weight must be greater than 0"	1001	{"key":"alternative_item"}
400	Could not resolve alternative item	"Could not resolve alternative item to a valid product"	1001	Not applicable
400	Order item change already responded to	"This order item change has already been responded to"	4001	Not applicable
400	Order item change no longer modifiable	"This order item change can no longer be modified"	4001	Not applicable
400	empty alternative_item hash	"cannot be empty"	1001	{"key":"alternative_item"}
400	alternative_item with APPROVED status	"can only be provided when status is REJECTED"	1001	{"key":"alternative_item"}
400	alternative_item without rrc or upc	"must include exactly one of rrc or upc"	1001	{"key":"alternative_item"}
400	Status not present*	"There were issues with your request"	9999	Not applicable
400	Status not valid	"is not included in the list"	1001	{"key":"status"}
400	Order was not created with Fulfillment v3, trying to fetch with client credentials	"User ID not found"	4001	Not applicable
404	No active order item change found	"No active order item change found for item qwertyuiop"	4000	Not applicable
404	Order not found	"Resource not found"	4000	Not applicable
404	Order item not found	"Order item 1111 not found"	4000	Not applicable

* Multiple error