> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.incarts.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Instacart links

> Create Instacart product detail, shopping list, and recipe links with retailer routing

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.

```bash theme={null}
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.

```json theme={null}
{
  "options": {
    "instacart": {
      "routingMode": "specific",
      "retailerId": "648"
    }
  }
}
```

### Preferred stores

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

```json theme={null}
{
  "options": {
    "instacart": {
      "routingMode": "preferred",
      "preferredRetailers": ["kroger", "aldi", "costco"]
    }
  }
}
```

### No preference

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

```json theme={null}
{
  "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"`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`). |

<Card title="Create link endpoint" icon="terminal" href="/api-reference/endpoint/create-link">
  Full schema, request playground, and response codes.
</Card>

<Card title="Find retailers endpoint" icon="store" href="/api-reference/endpoint/list-retailers">
  Search supported Instacart retailers and copy the right routing values.
</Card>