Create recipe page
POST /idp/v1/products/recipe
Creates a recipe page on Instacart Marketplace and generates a link to the page. When a user of your site or app clicks the generated link, the page opens and the user can select a store, add ingredients as products to a cart, and check out.
Each request must include an array of Ingredients
objects that represent products. For each line item, specify at least a product name. Instacart uses the product names to find matching products to display to your user, so make sure to add only the name in the name attribute. In other attributes, you can specify quantities, units of measurement, and filters. For a list of valid units, see Units of measurement.
Optionally, you can specify other page attributes, such as an image, description, and instructions. You can also include a link back to your site and specify if customers can exclude items they already have in their pantry.
- Cache the generated recipe page URL and reuse it. Don't generate a new URL unless the recipe changes. For more information, see Recipe page URL best practices.
- Only pass units listed in the supported Units of measurement page. If you pass a unit that is not listed, quantity matching will not work.
If a line_item
object includes a UPC, Instacart prioritizes the UPC to conduct the search. If the product is unavailable, Instacart notifies the user and provides the option to search for alternatives.
Multiple UPCs can be provided for a single line_item
as fallback options. The item shown to the user is determined by its availability and the order in which the UPCs are listed.
Note: Retailers offering an item searched via UPC are ranked higher in the retailer selection dropdown. If multiple UPCs are assigned to a line_item
, only the first UPC is considered for retailer ranking.
Authorization
Name | In | Description |
---|---|---|
Authorization | header | A bearer token. In this context, the token is the API key that you received from Instacart when you signed up for Instacart Developer Platform. |
URL parameters
None.Request body
Field | Type | Required | Description |
---|---|---|---|
title | string | ![]() | The title of the recipe. |
image_url | string | ![]() | The URL of the image to display on the recipe page. Image size must be 500x500 pixels. |
author | string | ![]() | The author of the recipe. |
servings | integer | ![]() | The number of servings the recipe makes. |
cooking_time | integer | ![]() | The time it takes to cook the recipe in minutes. |
external_reference_id | string | ![]() | The external reference ID of the recipe. |
content_creator_credit_info | string | ![]() | The content creator credit information. |
expires_in | integer | ![]() | The number of days until the link expires. The maximum value is 365 days. The default is 30 days. |
instructions | Array(string) | ![]() | Text that provides preparation and cooking instructions for the recipe. |
ingredients | Array(LineItem) | ![]() | The ingredients to include in the recipe. |
landing_page_configuration | LandingPageConfiguration | ![]() | The configuration for the recipe page. |
LineItem Object
Field | Type | Required | Description |
---|---|---|---|
name | string | ![]() | The product name. Instacart uses the product name as a search term to find a matching product. |
display_text | string | ![]() | The title of the matched ingredient to be displayed in the search results and ingredient list. If this is not provided, the 'name' field in the 'LineItem' object will be used. |
upcs | Array(string) | ![]() | The Universal Product Code (UPC) is a unique 12- or 14-digit identifier for a product. |
measurements | Array(Measurement) | ![]() | Measurement units used to specify the ingredient quantity in multiple ways. |
filters | Filter | ![]() | Optional filters used to specify product matching criteria. |
Measurement Object
Field | Type | Required | Description |
---|---|---|---|
quantity | number | ![]() | The product quantity. This value represents either the item count or measurement as defined by the 'unit' attribute. Used by Instacart to determine the quantity of this item to add. Defaults to 1.0. |
unit | string | ![]() | The unit of measurement associated with the quantity attribute. Some example units include each, package, tablespoon, teaspoon, ounce, or kilogram. For countable items such as tomatoes, it is recommended to use the 'each' value rather than specifying a weight. Defaults to each. |
Filter Object
Field | Type | Required | Description |
---|---|---|---|
brand_filters | Array(string) | ![]() | Optional brand filters to match products. Add the brand names to the `brand_filters` array separated by commas. The brand filter is case-sensitive. Brand names must be spelled exactly as they appear in the catalog. If 'upcs' are provided, this filter is ignored. |
health_filters | Array(string) | ![]() | Optional health filters to match products. Valid values are ORGANIC, GLUTEN_FREE, FAT_FREE, VEGAN, KOSHER, SUGAR_FREE, LOW_FAT. If 'upcs' are provided, this filter is ignored. |
LandingPageConfiguration Object
Field | Type | Required | Description |
---|---|---|---|
partner_linkback_url | string | ![]() | The URL link to the shopping list or recipe on the developer's app or website. |
enable_pantry_items | boolean | ![]() | Whether items can be marked as pantry items. Pantry items are items that a user might already have at home and doesn't need to add to the cart. Default is false. |
Request examples
- cURL
- Java
- Python
- Go
curl --request POST \
--url https://connect.instacart.com/idp/v1/products/recipe \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <API-key>' \
--header 'Content-Type: application/json' \
--data '{
"title": "string",
"image_url": "string",
"author": "string",
"servings": 1,
"cooking_time": 1,
"external_reference_id": "string",
"content_creator_credit_info": "string",
"expires_in": 1,
"instructions": [
"string"
],
"ingredients": [
{
"name": "string",
"display_text": "string",
"upcs": [
"string"
],
"measurements": [
{
"quantity": 1,
"unit": "string"
}
],
"filters": {
"brand_filters": [
"string"
],
"health_filters": [
"string"
]
}
}
],
"landing_page_configuration": {
"partner_linkback_url": "string",
"enable_pantry_items": true
}
}'
HttpResponse<String> response = Unirest.post("https://connect.instacart.com/idp/v1/products/recipe")
.header("Accept", "application/json")
.header("Content-Type", "application/json")
.header("Authorization", "Bearer <API-key>")
.body("{\n \"title\": \"string\",\n \"image_url\": \"string\",\n \"author\": \"string\",\n \"servings\": 1,\n \"cooking_time\": 1,\n \"external_reference_id\": \"string\",\n \"content_creator_credit_info\": \"string\",\n \"expires_in\": 1,\n \"instructions\": [\n \"string\"\n ],\n \"ingredients\": [\n {\n \"name\": \"string\",\n \"display_text\": \"string\",\n \"upcs\": [\n \"string\"\n ],\n \"measurements\": [\n {\n \"quantity\": 1,\n \"unit\": \"string\"\n }\n ],\n \"filters\": {\n \"brand_filters\": [\n \"string\"\n ],\n \"health_filters\": [\n \"string\"\n ]\n }\n }\n ],\n \"landing_page_configuration\": {\n \"partner_linkback_url\": \"string\",\n \"enable_pantry_items\": true\n }\n}")
.asString();
import http.client
conn = http.client.HTTPSConnection("connect.instacart.com")
payload = "{\n \"title\": \"string\",\n \"image_url\": \"string\",\n \"author\": \"string\",\n \"servings\": 1,\n \"cooking_time\": 1,\n \"external_reference_id\": \"string\",\n \"content_creator_credit_info\": \"string\",\n \"expires_in\": 1,\n \"instructions\": [\n \"string\"\n ],\n \"ingredients\": [\n {\n \"name\": \"string\",\n \"display_text\": \"string\",\n \"upcs\": [\n \"string\"\n ],\n \"measurements\": [\n {\n \"quantity\": 1,\n \"unit\": \"string\"\n }\n ],\n \"filters\": {\n \"brand_filters\": [\n \"string\"\n ],\n \"health_filters\": [\n \"string\"\n ]\n }\n }\n ],\n \"landing_page_configuration\": {\n \"partner_linkback_url\": \"string\",\n \"enable_pantry_items\": true\n }\n}"
headers = {
'Accept': "application/json",
'Content-Type': "application/json",
'Authorization': "Bearer <API-key>"
}
conn.request("POST", "/idp/v1/products/recipe", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://connect.instacart.com/idp/v1/products/recipe"
payload := strings.NewReader("{\n \"title\": \"string\",\n \"image_url\": \"string\",\n \"author\": \"string\",\n \"servings\": 1,\n \"cooking_time\": 1,\n \"external_reference_id\": \"string\",\n \"content_creator_credit_info\": \"string\",\n \"expires_in\": 1,\n \"instructions\": [\n \"string\"\n ],\n \"ingredients\": [\n {\n \"name\": \"string\",\n \"display_text\": \"string\",\n \"upcs\": [\n \"string\"\n ],\n \"measurements\": [\n {\n \"quantity\": 1,\n \"unit\": \"string\"\n }\n ],\n \"filters\": {\n \"brand_filters\": [\n \"string\"\n ],\n \"health_filters\": [\n \"string\"\n ]\n }\n }\n ],\n \"landing_page_configuration\": {\n \"partner_linkback_url\": \"string\",\n \"enable_pantry_items\": true\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 <API-key>")
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 |
---|---|---|---|
products_link_url | string | ![]() | Products link URL. |
Response examples
200 Success
200
Create a recipe successfully without affiliate_id200
Create a recipe successfully with affiliate_id
{
"products_link_url": "http://example.com"
}
{
"products_link_url": "http://example.com?aff_id=123&offer_id=1&affiliate_platform=idp_partner"
}
4XX Errors
Error responses return either a single error or multiple errors.
HTTP Code | Cause | Error Message | Error Code | Error Meta |
---|---|---|---|---|
400 | Bad request missing required parameters* | "There were issues with your request" | 9999 | Not applicable |
400 | Bad request invalid health filters | "Invalid health filters: ["INVALID"]" | 1001 | {"key":"ingredients[0].filters.health_filters"} |
400 | Bad request invalid measurement quantity | "Invalid quantity: -0.1. Cannot be lower than or equal to 0.0" | 1001 | {"key":"ingredients[0].measurements[0].quantity"} |
400 | Bad request duplicate upcs across ingredients | "Duplicate product identifiers found: upc 123456789012" | 1001 | {"key":"ingredients"} |