Find replacement items (backend)

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

Returns a user's recommended replacement items. For each item in the request body, 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
user_id	path	string		The ID of the user.

Request

Field	Type	Required	Description
location_code	string		The location code of the store to use for inventory. Replacement items are selected from this store.
cart_id	string		The ID of the cart.
max_replacement_items	integer		The maximum number of suggested replacement items to be returned for each item. Defaults to 5.
items	Array(Line)		An array of items. Replacement items are retrieved for each of these items.

Line Object

Field	Type	Required	Description
line_num	string		The line number.
item	Item		The item.

Item Object

One of the following:

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

or

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

Request examples

cURL

curl --request POST \
  --url 'https://connect.instacart.com/v2/recommendations/users/{user_id}/replacement_items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_code": "string",
  "cart_id": "string",
  "max_replacement_items": 1,
  "items": [
    {
      "line_num": "string",
      "item": {
        "rrc": "string"
      }
    }
  ]
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/recommendations/users/{user_id}/replacement_items")
  .header("Accept", "application/json")
  .header("Content-Type", "application/json")
  .header("Authorization", "Bearer <token>")
  .body("{\n  \"location_code\": \"string\",\n  \"cart_id\": \"string\",\n  \"max_replacement_items\": 1,\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"item\": {\n        \"rrc\": \"string\"\n      }\n    }\n  ]\n}")
  .asString();

Python

import http.client

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

payload = "{\n  \"location_code\": \"string\",\n  \"cart_id\": \"string\",\n  \"max_replacement_items\": 1,\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"item\": {\n        \"rrc\": \"string\"\n      }\n    }\n  ]\n}"

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

conn.request("POST", "/v2/recommendations/users/{user_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}/replacement_items"

	payload := strings.NewReader("{\n  \"location_code\": \"string\",\n  \"cart_id\": \"string\",\n  \"max_replacement_items\": 1,\n  \"items\": [\n    {\n      \"line_num\": \"string\",\n      \"item\": {\n        \"rrc\": \"string\"\n      }\n    }\n  ]\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": "1",
      "item": {
        "upc": "00000000000000",
        "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	Store not found	"Could not find specified store."	1001	{"key":"location_code"}
400	User not found	"User Not Found"	1001	{"key":"user_id"}