Find replacement items for an order (backend)

POST /v2/recommendations/users/{user_id}/orders/{order_id}/replacement_items

Returns a user's recommended replacement items for an order. For each item in an order, returns an array of suggested replacement items that are available in the selected store. By default, an item can have up to five replacement items.

info

Use this endpoint with a client credentials access token for backend implementations. For frontend implementations, see Find replacement items for an order (frontend).

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

Field	Type	Required	Description
max_replacement_items	integer		The maximum number of suggested replacement items to be returned for each item. Defaults to 5.

Request examples

cURL

curl --request POST \
  --url 'https://connect.instacart.com/v2/recommendations/users/{user_id}/orders/{order_id}/replacement_items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "max_replacement_items": 1
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/recommendations/users/{user_id}/orders/{order_id}/replacement_items")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"max_replacement_items\": 1\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"max_replacement_items\": 1\n}"

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

conn.request("POST", "/v2/recommendations/users/{user_id}/orders/{order_id}/replacement_items", payload, headers)

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

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

Go

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"max_replacement_items\": 1\n}")

	req, _ := http.NewRequest("POST", 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, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}

Response

Field	Type	Required	Description
items	Array(Line)		The items and their suggested replacement items.

Line Object

Field	Type	Required	Description
line_num	string		The line number.
item	Item		The item.
replacement_items	Array(Item)		The suggested replacement items.

Item Object

Field	Type	Required	Description
rrc	string		The item's retailer reference code (rrc).
upc	string		The item's universal product code (upc).
stock_level	string		The stock level of the item. One of IN_STOCK, LOW_STOCK, or OUT_OF_STOCK.

Response examples

200 Success

200 Suggested replacement items returned

{
  "items": [
    {
      "line_num": "301",
      "item": {
        "upc": "123456789308",
        "stock_level": "in_stock"
      },
      "replacement_items": [
        {
          "upc": "11111111111111",
          "stock_level": "in_stock"
        }
      ]
    }
  ]
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP Code	Cause	Error Message	Error Code	Error Meta
400	User not found	"User Not Found"	1001	{"key":"user_id"}
404	Order not found	"Resource not found"	4000	Not applicable