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 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 products to a cart, and check out.

Each request must include an array of LineItem 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. You can also 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.

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 shopping list or recipe page.
image_urlstringOptionalThe URL of the image to display on the shopping list or recipe page. Image size must be 500x500 pixels.
link_typestringOptionalThe type of product link to create. One of 'shopping_list' or 'recipe'. Defaults to shopping_list.
expires_inintegerOptionalThe 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)OptionalText that provides additional context about the shopping list or recipe, such as instructions for making a recipe or a dietary recommendation.
line_itemsArray(LineItem)RequiredThe line items (products) to include in the shopping list or recipe.
landing_page_configurationLandingPageConfigurationOptionalThe configuration for the shopping list or recipe page.

LineItem Object​

FieldTypeRequiredDescription
namestringRequiredThe product name. Instacart uses the product name as a search term to find a matching product.
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.
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.
line_item_measurementsArray(Measurement)OptionalOptional 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.
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 in the catalog.
health_filtersArray(string)OptionalOptional health filters to match products. Valid values are ORGANIC, GLUTEN_FREE, FAT_FREE, VEGAN, KOSHER, SUGAR_FREE, LOW_FAT.

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 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",
      "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_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":"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"}
* Multiple error
Last updated on