Find complementary items (backend)

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

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

info

Use this endpoint with a client credentials access token for backend implementations. For frontend implementations, see Find complementary items (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. Complementary items are selected from this store.
cart_id	string		The ID of the cart.
max_complementary_items	integer		The maximum number of suggested complementary items to be returned. Defaults to 5.
items	Array(Line)		An array of items. Complementary 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}/complementary_items' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_code": "string",
  "cart_id": "string",
  "max_complementary_items": 1,
  "items": [
    {
      "line_num": "string",
      "item": {
        "rrc": "string"
      }
    }
  ]
}'

Java

HttpResponse<String> response = Unirest.post("https://connect.instacart.com/v2/recommendations/users/{user_id}/complementary_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_complementary_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_complementary_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}/complementary_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}/complementary_items"

	payload := strings.NewReader("{\n  \"location_code\": \"string\",\n  \"cart_id\": \"string\",\n  \"max_complementary_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
complementary_items	Array(Item)		The suggested complementary 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).

Response examples

200 Success

200 Suggested complementary items returned

{
  "complementary_items": [
    {
      "upc": "11111111111111"
    }
  ]
}

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