Skip to main content

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

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

Parameters

NameInTypeRequiredDescription
user_idpathstringRequiredThe ID of the user.

Request

FieldTypeRequiredDescription
location_codestringRequiredThe location code of the store to use for inventory. Complementary items are selected from this store.
cart_idstringOptionalThe ID of the cart.
max_complementary_itemsintegerOptionalThe maximum number of suggested complementary items to be returned. Defaults to 5.
itemsArray(Line)RequiredAn array of items. Complementary items are retrieved for each of these items.

Line Object

FieldTypeRequiredDescription
line_numstringOptionalThe line number.
itemItemRequiredThe item.

Item Object

One of the following:

FieldTypeRequiredDescription
rrcstringRequiredThe item's retailer reference code (rrc).

or

FieldTypeRequiredDescription
upcstringRequiredThe item's universal product code (upc).

Request examples

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

Response

FieldTypeRequiredDescription
complementary_itemsArray(Item)OptionalThe suggested complementary items.

Item Object

FieldTypeRequiredDescription
rrcstringOptionalThe item's retailer reference code (rrc).
upcstringOptionalThe item's universal product code (upc).

Response examples

200 Success

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

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Store not found"Could not find specified store."1001{"key":"location_code"}
400User not found"User Not Found"1001{"key":"user_id"}