Instacart links

Instacart links require retailer: "instacart" and intent: "product_detail", intent: "shopping_list", or intent: "recipe". Your API key must include the retailers:instacart scope.

Retailer routing

For Instacart, the top-level retailer: "instacart" identifies the link provider — not the grocery store. Choose which store the shopper lands on with options.instacart. Use GET /v1/retailers to find the values accepted by each Instacart link type.

curl "$INCARTS_API_BASE_URL/v1/retailers?provider=instacart&query=target&limit=10" \
  --header "X-Incarts-API-Key: $INCARTS_API_KEY"

The response includes intent-specific usage:

Use usage.shoppingList.retailerId as options.instacart.retailerId for shopping list links.
Use usage.recipe.retailerId as options.instacart.retailerId for recipe links.
Use usage.productDetail.retailer as options.instacart.retailer for product detail links.

Specific store

Use routingMode: "specific" when you know the exact store. For product detail links, send retailer with the Instacart store slug. Incarts appends it as retailerSlug on the Instacart product URL. For shopping list and recipe links, provide retailerId (the Instacart numeric ID) for precise routing.

{
  "options": {
    "instacart": {
      "routingMode": "specific",
      "retailerId": "648"
    }
  }
}

Preferred stores

Use routingMode: "preferred" with an ordered list of store slugs. Incarts tries each in order.

{
  "options": {
    "instacart": {
      "routingMode": "preferred",
      "preferredRetailers": ["kroger", "aldi", "costco"]
    }
  }
}

No preference

Use routingMode: "no_preference" (the default) to let Instacart choose the store automatically.

{
  "options": {
    "instacart": {
      "routingMode": "no_preference"
    }
  }
}

Product detail links

Set intent: "product_detail" and provide exactly one item in products. Use the Instacart product ID from the /products/{id} path, not a UPC. For a retailer-specific product page such as https://www.instacart.com/products/98343-pepsi-cola-16-9-fl-oz?retailerSlug=walgreens, send retailerProductId: "98343" and options.instacart.retailer: "walgreens".

{
  "projectId": "proj_123",
  "name": "Instacart Walgreens Pepsi PDP",
  "publicName": "Shop Pepsi at Walgreens",
  "retailer": "instacart",
  "intent": "product_detail",
  "products": [
    {
      "retailerProductId": "98343",
      "quantity": 1
    }
  ],
  "options": {
    "instacart": {
      "routingMode": "specific",
      "retailer": "walgreens"
    }
  }
}

Shopping list links

Set intent: "shopping_list" and provide options.instacart.shoppingList with a title and line items.

{
  "projectId": "proj_123",
  "name": "Instacart breakfast list",
  "publicName": "Shop the breakfast list",
  "retailer": "instacart",
  "intent": "shopping_list",
  "options": {
    "instacart": {
      "routingMode": "specific",
      "retailerId": "648",
      "shoppingList": {
        "title": "Weekend breakfast",
        "imageUrl": "https://assets.example.com/weekend-breakfast.jpg",
        "instructions": "Buy the freshest items available.",
        "lineItems": [
          {
            "name": "eggs",
            "quantity": 1,
            "unit": "dozen",
            "upcs": ["0001111000001"],
            "catalogProductId": "prod_eggs",
            "backupProductIds": ["prod_large_brown_eggs"],
            "backupUpcs": ["0001111000002"]
          },
          {
            "name": "whole milk",
            "quantity": 1,
            "unit": "gallon",
            "upcs": ["0001111000003"]
          }
        ]
      }
    }
  },
  "tracking": {
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "breakfast-promo"
    },
    "tags": ["breakfast", "dairy"]
  }
}

Shopping list fields

Field	Type	Required	Description
`title`	string	Yes	List title shown to shoppers. Max 160 characters.
`lineItems`	array	Yes	Items in the list. 1-200 items.
`imageUrl`	string (URI)	No	Hero image for the shopping list.
`instructions`	string	No	Instructions for the shopper. Max 4000 characters.

Recipe links

Set intent: "recipe" and provide options.instacart.recipe with a title and ingredients.

{
  "projectId": "proj_123",
  "name": "Instacart tomato toast recipe",
  "publicName": "Shop the recipe",
  "retailer": "instacart",
  "intent": "recipe",
  "options": {
    "instacart": {
      "routingMode": "no_preference",
      "recipe": {
        "title": "Tomato toast",
        "author": "Incarts",
        "imageUrl": "https://assets.example.com/tomato-toast.jpg",
        "servings": 4,
        "cookingTimeMinutes": 15,
        "instructions": [
          "Toast the sourdough slices until golden.",
          "Slice tomatoes and layer on toast.",
          "Drizzle with olive oil, salt, and pepper."
        ],
        "expiresInDays": 30,
        "ingredients": [
          {
            "name": "tomatoes",
            "quantity": 4,
            "unit": "whole",
            "upcs": ["0001111000004"],
            "catalogProductId": "prod_tomatoes",
            "backupProductIds": ["prod_cherry_tomatoes"],
            "backupUpcs": ["0001111000005"],
            "filters": {
              "healthFilters": ["ORGANIC"]
            }
          },
          {
            "name": "sourdough bread",
            "quantity": 1,
            "unit": "loaf"
          }
        ],
        "landingPageConfiguration": {
          "partnerLinkbackUrl": "https://yoursite.com/recipes/tomato-toast",
          "enablePantryItems": true
        }
      }
    }
  }
}

Recipe fields

Field	Type	Required	Description
`title`	string	Yes	Recipe title. Max 160 characters.
`ingredients`	array	Yes	Recipe ingredients. 1-200 items.
`author`	string	No	Recipe author name. Max 160 characters.
`imageUrl`	string (URI)	No	Hero image for the recipe.
`servings`	integer	No	Number of servings.
`cookingTimeMinutes`	integer	No	Cooking time in minutes.
`instructions`	array of strings	No	Step-by-step cooking instructions.
`expiresInDays`	integer	No	Days until the link expires (1-365).
`landingPageConfiguration`	object	No	See below.

Landing page configuration

Field	Type	Description
`partnerLinkbackUrl`	string (URI)	Link back to the recipe on your site, shown on the Instacart landing page.
`enablePantryItems`	boolean	Let Instacart suggest common pantry items alongside recipe ingredients.

Line item and ingredient fields

Shopping list line items and recipe ingredients share the same field structure.

Field	Type	Required	Description
`name`	string	Yes	Item name. Max 200 characters.
`quantity`	number	No	Quantity (default: 1).
`unit`	string	No	Unit of measure (e.g. `each`, `dozen`, `lb`). Max 64 characters.
`upcs`	array of strings	No	UPCs for Instacart product matching. Include primary and backup UPCs.
`backupUpcs`	array of strings	No	Backup UPCs merged into the Instacart `upcs` field. Max 25.
`catalogProductId`	string	No	Incarts catalog product ID for dashboard metadata. Not sent to Instacart.
`backupProductIds`	array of strings	No	Incarts catalog IDs for backup choices. Max 25.
`displayText`	string	No	Alternative display text. Max 200 characters.
`measurements`	array	No	Structured measurements (e.g. `[{"quantity": 2, "unit": "lbs"}]`).
`filters`	object	No	Brand and health filters. See below.

Filters

Field	Type	Description
`brandFilters`	array of strings	Restrict results to specific brands.
`healthFilters`	array of strings	Health attribute filters (e.g. `ORGANIC`, `GLUTEN_FREE`).

Create link endpoint

Full schema, request playground, and response codes.

Find retailers endpoint

Search supported Instacart retailers and copy the right routing values.

Get started

Core workflows

In development

Retailer routing

Specific store

Preferred stores

No preference

Product detail links

Shopping list links

Shopping list fields

Recipe links

Recipe fields

Landing page configuration

Line item and ingredient fields

Filters

Create link endpoint

Find retailers endpoint

​Retailer routing

​Specific store

​Preferred stores

​No preference

​Product detail links

​Shopping list links

​Shopping list fields

​Recipe links

​Recipe fields

​Landing page configuration

​Line item and ingredient fields

​Filters

Create link endpoint

Find retailers endpoint

Retailer routing

Specific store

Preferred stores

No preference

Product detail links

Shopping list links

Shopping list fields

Recipe links

Recipe fields

Landing page configuration

Line item and ingredient fields

Filters