Shopping list page

Instacart Developer Platform provides unique flexibility in the design of shopping lists. With access to stores in multiple locations across North America, you can build shopping lists that cater to different use cases while avoiding administrative overhead and inventory management.

Some use cases for shopping lists include:

• Cleaning and laundry
• Pet focused lists
• Health and personal care
• Party and gift supplies
• Winter needs

The basics - step by step

The following workflow describes the steps to create and use a shopping list:

1. Identify the products that make up the shopping list.
2. Add these products to the line_items parameter when making a request to the Create shopping list page endpoint.
3. When successful, the request returns a URL to the shopping list page on Instacart Marketplace. You associate this URL with the shopping list in your application.
4. From your application, a user clicks the link.
5. On the shopping list page, the user selects their preferred store, reviews the items available in that store, and adds their preferred items to their cart.
6. If the user is already logged into Instacart, they can proceed to checkout. Otherwise, the user is prompted to log in or to create an account.

The following image shows an example of a shopping list page:

Related topics

• Create shopping list page endpoint

Ingredients

With the Create a Shopping list page API, you can tailor ingredient presentations to include ingredient names, custom display text, single or multiple measurements.

Update ingredient display text

By default, the name field defines the display text for an ingredient. Instacart uses this field to find matching products and display the ingredient name in the Items and Full Items lists.

For additional customization, the display_text field can be used to override the default display name, allowing greater flexibility in how the ingredient appears.

Shopping list page ingredients

1. Ingredient display name.

Code snippet

{
  "line_items": [
    {
      "name": "tofu",
      "line_item_measurements": [
        {
          "quantity": "14",
          "unit": "oz"
        },
        {
          "quantity": "600",
          "unit": "g"
        }
      ]
    },
    {
      "name": "avocado",
      "display_text": "15 oz avocado",
      "line_item_measurements": [
        {
          "quantity": "14",
          "unit": "oz"
        },
        {
          "quantity": "600",
          "unit": "g"
        }
      ]
    }
  ]
}

By default, the name field is used to query Instacart for an item and to set the ingredient’s display name in both the Items and Full Items list.

Alternatively, the display name can be customized using the display_text field.

note

When using display_text, the name field is still required to query an item.

Work with measurements

The line_item_measurements array allows you to define one or more measurements for an ingredient. Including multiple measurements enhances flexibility and improves the user experience by accommodating different measurement preferences. It can also increase the accuracy of product quantity conversions.

Here are some reasons you may want to consider using multiple measurements:

• Different users may prefer different units of measurement, and offering multiple options improves customer convenience.
• Some units cannot be directly converted into others. Including additional measurements can help to ensure that a compatible unit for the item quantity calculation is always available. For more information, see Units of measurement.

In the example below, the ingredient "drizzle honey" includes two measurements: 48 ounces and 1418 milliliters. Instacart calculates the product quantity based on the order of the measurements in the array, starting with the first measurement listed.

Additionally, the Items List on the Shopping list page displays the configured measurements for each ingredient. This helps users better understand the required quantities and ensures they have the option to pick units they are most familiar with from the Full Items List. In this example, both measurements (ounces and milliliters) are shown, providing convenience and clarity for shoppers.

Shopping list page ingredients

Code snippet

{
    "line_items": [
        {
            "name": "drizzle honey",
            "line_item_measurements": [
                {
                    "quantity": "48",
                    "unit": "oz"
                },
                {
                    "quantity": "1418",
                    "unit": "ml"
                }
            ]
        }
    ]
}

note

Instacart calculates the product quantity for each unit defined in the line_item_measurements array.