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.
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. |
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. |
health_filters | Array(string) | ![]() | Optional health filters to match products. Valid values are ORGANIC, GLUTEN_FREE, FAT_FREE, VEGAN, KOSHER, SUGAR_FREE, LOW_FAT. |
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",
"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 \"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 \"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 \"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"} |