Skip to main content

Create shopping list page

POST /idp/v1/products/products_link

Creates a shopping list page on Instacart Marketplace and generates a shareable link. When users click the link, they can select a store, add products to their cart, and check out.

Prerequisites​

Before you begin, ensure you have:

note

When ready for production, create a production API key and update your endpoint to: https://connect.instacart.com.

Request structure​

Each request must include an array of LineItem objects representing products. At minimum, specify a product name for each line item. Instacart uses product names to match and display products to users. When creating a LineItem object, determine whether the ingredient has a single measurement or multiple measurements. For example:

  • Single measurement. A shopping list LineItem might be a 10.75 fl oz can of tomato soup.
  • Multiple measurements. A shopping list LineItem could include flour listed as 1 cup / 16 tbsp / 48 tsp.

Use the line_item_measurements array to specify measurement options for each line item. This array allows retailers to provide multiple measurements, so that Instacart can choose the best one for calculating the quantity. The quantity and unit fields directly on the LineItem object are deprecated. Use line_item_measurements instead.

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.

Optional line item fields​

  • Quantities.
  • Units of measurement (see Units of measurement for valid values).
  • Filters.
  • UPC codes.
tip

When a line_item includes a UPC, Instacart prioritizes UPC-based search. If the product is unavailable, users are notified and can search for alternatives.

Best practices​

  • URL Caching. Cache the generated shopping list URL and reuse it. Only generate a new URL when the shopping list content changes.
  • Units of Measurement. Only use units listed in the supported Units of measurement page. Unsupported units cause quantity matching to fail.

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
titlestringRequired

The title of the shopping list or recipe page.

image_urlstringOptional

The URL of the image to display on the shopping list or recipe page. Image size must be 500x500 pixels.

link_typestringOptional

The type of product link to create. One of 'shopping_list' or 'recipe'. Defaults to shopping_list.

expires_inintegerOptional

The number of days until the link expires. The maximum value is 365 days. When the link_type is 'recipe', the default is 30 days. When the link_type is 'shopping_list', there is no default value.

instructionsArray(string)Optional

Text that provides additional context about the shopping list or recipe, such as instructions for making a recipe or a dietary recommendation.

line_itemsArray(LineItem)Required

The line items (products) to include in the shopping list or recipe.

landing_page_configurationLandingPageConfigurationOptional

The configuration for the shopping list or recipe page.

LineItem Object​

FieldTypeRequiredDescription
namestringRequired

The product name. Instacart uses the product name as a search term to find a matching product.

quantitynumberOptional

Deprecated. Use the 'line_item_measurements' array instead, which allows multiple measurements per line item. The product quantity. This value represents either the item count or measurement as defined by the 'unit' attribute. Defaults to 1.0.

unitstringOptional

Deprecated. Use the 'line_item_measurements' array instead, which allows multiple measurements per line item. The unit of measurement associated with the quantity attribute. Some example units include each, package, tablespoon, teaspoon, ounce, or kilogram. Defaults to each.

display_textstringOptional

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.

product_idsArray(integer)Optional

The product IDs used to map ingredients to specific products. 'product_id' and 'upc' are mutually exclusive.

upcsArray(string)Optional

The Universal Product Code (UPC) is a unique 12- or 14-digit identifier for a product. 'product_id' and 'upc' are mutually exclusive.

line_item_measurementsArray(Measurement)Optional

Optional measurement units used to specify the ingredient quantity in multiple ways. If this is not provided, the 'unit' and 'quantity' fields in the 'LineItem' object will be used.

filtersFilterOptional

Optional filters used to specify product matching criteria.

Measurement Object​

FieldTypeRequiredDescription
quantitynumberOptional

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.

unitstringOptional

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​

FieldTypeRequiredDescription
brand_filtersArray(string)Optional

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 on Instacart. If 'product_ids' or 'upcs' are provided, this filter is ignored.

health_filtersArray(string)Optional

Optional 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_urlstringOptional

The URL link to the shopping list or recipe on the developer's app or website.

enable_pantry_itemsbooleanOptional

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 and only supported on 'recipe' link_type.

Request examples​

curl --request POST \
  --url https://connect.instacart.com/idp/v1/products/products_link \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <API-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "title": "string",
  "image_url": "string",
  "link_type": "string",
  "expires_in": 1,
  "instructions": [
    "string"
  ],
  "line_items": [
    {
      "name": "string",
      "quantity": 1,
      "unit": "string",
      "display_text": "string",
      "product_ids": [
        1
      ],
      "upcs": [
        "string"
      ],
      "line_item_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_urlstringRequired

Products 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":"line_items[0].filters.health_filters"}
400Bad request invalid measurement quantity"Invalid quantity: -0.1. Cannot be lower than or equal to 0.0"1001{"key":"line_items[0].line_item_measurements[0].quantity"}
400Bad request line item with both product_ids and upcs"Line item cannot have both product_ids and upcs. They are mutually exclusive."1001{"key":"line_items[0].base"}
400Bad request duplicate product_ids across line items"Duplicate product identifiers found: product_id 12345"1001{"key":"line_items"}
400Bad request duplicate upcs across line items"Duplicate product identifiers found: upc 123456789012"1001{"key":"line_items"}
* Multiple error
Last updated on