Create a recipe page

Learn how to create a recipe page with Instacart Developer Platform API.

In this tutorial, we send a request to generate a recipe page with following elements:

• Recipe title and image.
• A list of ingredients and their specified quantities.
• A collection of nearby stores on Instacart Marketplace that have the recipe ingredients.
• Instructions on how to prepare the meal or dish.

The generated recipe page is hosted on Instacart Marketplace. In a production environment, you share the links to recipe pages from your app or website. Your users can click a link to go to the recipe page, select the ingredients they need, and add them to their cart.

note

Any API requests you make in development or production will not translate to an order unless you check out a cart on Instacart Marketplace.

Before you begin

For this tutorial, you need the following items:

• An API key. You received this key when you signed up for Instacart Developer Platform.
• Instacart's development server: https://connect.dev.instacart.tools. When you are ready to move to production, you'll specify the production server in your requests: https://connect.instacart.com.

Create a recipe

To create a recipe, we need the recipe’s title, a link to an image that depicts the recipe’s theme, ingredients that make up the recipe, and instructions on how to prepare the recipe. In this example, we prepare to build a recipe page for a chocolate cake recipe.

The following table lists the fields to specify for this recipe:

Field name	Description	Value
title	The recipe page’s title.	Small Chocolate Cake (6 inches)
image_url	A link to an image that shows the theme/detail of the recipe page. The image can be hosted on any content delivery network (CDN).	https://d3s8tbcesxr4jm.cloudfront.net/recipe-images/v3/small-chocolate-cake-6-inches/0_medium.jpg
instructions	Step-by-step instructions on how to make the cake.	Preheat the oven to 350 degrees F and grease a 6-inch round cake pan. In a large bowl, combine flour, sugar, cocoa, baking powder, baking soda, salt, and cinnamon. Add egg, milk, oil, and vanilla to dry ingredients and mix well. Gradually add boiling water, mixing continuously until the batter is smooth. Pour the batter in the prepared cake pan and bake for 30-35 minutes, or until a toothpick comes out clean. Let the cake cool in the pan for 10 minutes, then remove from the pan and let cool completely on a wire rack. To prepare the frosting, melt the butter in a small saucepan. Stir in the cocoa and remove the saucepan from heat. Gradually add powdered sugar and milk, stirring until you reach your desired consistency. Stir in the vanilla. Wait until the cake is cooled completely to frost it.
ingredients	A list of ingredients used in making the cake, their respective quantities, and measurement units.	1/2 cup whole milk 1 large egg 1/4 teaspoon ground cinnamon 1/4 teaspoon salt 1 teaspoon baking powder 1/2 teaspoon baking soda 1/4 cup unsalted butter 1/4 cup unsweetened cocoa powder 1 cup powdered sugar 1-2 tablespoons milk 1/2 teaspoon vanilla extract 1/2 cup boiling water 1 teaspoon vanilla extract 1/4 cup vegetable oil 1 cup all-purpose flour 1 cup granulated sugar 1/2 cup unsweetened cocoa powder
partner_linkback_url	A link to guide customers back to your website after they are done with Instacart Marketplace.	https://example.com/recipes
enable_pantry_items	A boolean option that when set to true, indicates the ingredients your customer may already have and don’t need to purchase for now.	true

Make an API request for your recipe page

To build the recipe page, make an API request to the /idp/v1/products/recipe endpoint.

The following code sample shows how to structure the request. Some parts of the code sample have been shortened to improve clarity, such as the instructions and ingredients fields:

curl --request POST \
  --url 'https://connect.dev.instacart.tools/idp/v1/products/recipe' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY_HERE>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Small Chocolate Cake (6 inches)",
    "image_url": "https://d3s8tbcesxr4jm.cloudfront.net/recipe-images/v3/small-chocolate-cake-6-inches/0_medium.jpg",
    "link_type": "recipe",
    "instructions": [
      "Preheat the oven to 350 degrees F and grease a 6-inch round cake pan.",
      "In a large bowl, combine flour, sugar, cocoa, baking powder, baking soda, salt, and cinnamon.",
      "Add egg, milk, oil, and vanilla to dry ingredients and mix well."
    ],
    "ingredients": [
      {
        "name": "whole milk",
        "quantity": 0.5,
        "unit": "cup"
      },
      {
        "name": "egg",
        "quantity": 1,
        "unit": "large"
      },
      {
        "name": "ground cinnamon",
        "quantity": 0.25,
        "unit": "teaspoon"
      }
    ],
    "landing_page_configuration": {
      "partner_linkback_url": "string",
      "enable_pantry_items": true
    }
  }'

The response for this request contains a link to the recipe page:

{
  "products_link_url": "https://www.instacart.com/store/recipes/396179?aff_id=4204&offer_id=1&affiliate_platform=idp_partner"
}

Verify the recipe page

Test the link. Verify that the recipe page opens on Instacart Marketplace and contains all the information we sent in the request.

The following image shows the recipe page containing these values:

• Title and image for the recipe.
• A selection of stores that carry the recipe ingredients.
• The ingredients available in the selected store.
• The ingredients that the customer may already have in their pantry.
• The full list of ingredients with measurements.
• Instructions on how to prepare the ingredients.

Share the recipe link with your users

In a production environment, you'll share the link from your website or app. Your customer can select a store and the ingredients they prefer from the recipe page. When they are satisfied with their selections, they can go to checkout.

The following image shows a customer’s cart ready for checkout:

To try this out yourself, copy this sample request and substitute in your API key.

Summary

In this tutorial, we created a recipe page. We planned out the details for the recipe, and then sent an API request to the Instacart Developer Platform API with the details. The API request returned a link that redirects to the recipe page on Instacart Marketplace. Finally, we showed how customers can fill their carts with the ingredients they need.