Skip to main content

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.

Best practice
  • 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.
tip

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​

NameInDescription
AuthorizationheaderA 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​

FieldTypeRequiredDescription
titlestringRequiredThe title of the recipe.
image_urlstringOptionalThe URL of the image to display on the recipe page. Image size must be 500x500 pixels.
authorstringOptionalThe author of the recipe.
servingsintegerOptionalThe number of servings the recipe makes.
cooking_timeintegerOptionalThe time it takes to cook the recipe in minutes.
external_reference_idstringOptionalThe external reference ID of the recipe.
content_creator_credit_infostringOptionalThe content creator credit information.
expires_inintegerOptionalThe number of days until the link expires. The maximum value is 365 days. Default is 30 days.
instructionsArray(string)OptionalText that provides preparation and cooking instructions for the recipe.
ingredientsArray(LineItem)RequiredThe ingredients to include in the recipe.
landing_page_configurationLandingPageConfigurationOptionalThe configuration for the recipe page.

LineItem Object​

FieldTypeRequiredDescription
namestringRequiredThe product name. Instacart uses the product name as a search term to find a matching product.
display_textstringOptionalThe 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.
product_idsArray(integer)OptionalThe product IDs used to map ingredients to specific products. 'product_id' and 'upc' are mutually exclusive.
upcsArray(string)OptionalThe Universal Product Code (UPC) is a unique 12- or 14-digit identifier for a product. 'product_id' and 'upc' are mutually exclusive.
measurementsArray(Measurement)OptionalMeasurement units used to specify the ingredient quantity in multiple ways.
filtersFilterOptionalOptional filters used to specify product matching criteria.

Measurement Object​

FieldTypeRequiredDescription
quantitynumberOptionalThe 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.
unitstringOptionalThe 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​

FieldTypeRequiredDescription
brand_filtersArray(string)OptionalOptional 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 on Instacart. If 'product_ids' or 'upcs' are provided, this filter is ignored.
health_filtersArray(string)OptionalOptional health filters to match products. Valid values are ORGANIC, GLUTEN_FREE, FAT_FREE, VEGAN, KOSHER, SUGAR_FREE, LOW_FAT. If 'product_ids' or 'upcs' are provided, this filter is ignored.

LandingPageConfiguration Object​

FieldTypeRequiredDescription
partner_linkback_urlstringOptionalThe URL link to the shopping list or recipe on the developer's app or website.
enable_pantry_itemsbooleanOptionalWhether 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 --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",
      "product_ids": [
        1
      ],
      "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
  }
}'

Response​

FieldTypeRequiredDescription
products_link_urlstringRequiredProducts link URL.

Response examples​

200 Success

{
  "products_link_url": "http://example.com"
}

4XX Errors

Error responses return either a single error or multiple errors.

HTTP CodeCauseError MessageError CodeError Meta
400Bad request missing required parameters*"There were issues with your request"9999Not applicable
400Bad request invalid health filters"Invalid health filters: ["INVALID"]"1001{"key":"ingredients[0].filters.health_filters"}
400Bad request invalid measurement quantity"Invalid quantity: -0.1. Cannot be lower than or equal to 0.0"1001{"key":"ingredients[0].measurements[0].quantity"}
400Bad request ingredient with both product_ids and upcs"Line item cannot have both product_ids and upcs. They are mutually exclusive."1001{"key":"ingredients[0].base"}
400Bad request duplicate product_ids across ingredients"Duplicate product identifiers found: product_id 12345"1001{"key":"ingredients"}
400Bad request duplicate upcs across ingredients"Duplicate product identifiers found: upc 123456789012"1001{"key":"ingredients"}
* Multiple error
Last updated on