> ## 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.

# Walmart links

> Create Walmart add-to-cart links with smart-select and product backups

Walmart links use `retailer: "walmart"` with `intent: "add_to_cart"` or
`intent: "product_detail"`. Add-to-cart accepts one or more Walmart item IDs; product detail
requires exactly one.

## Basic add-to-cart

This creates a direct add-to-cart link from the product IDs in the request.

```json theme={null}
{
  "projectId": "proj_123",
  "name": "Summer grilling basket",
  "publicName": "Shop the grilling list",
  "retailer": "walmart",
  "intent": "add_to_cart",
  "products": [
    {
      "retailerProductId": "123456789",
      "quantity": 1,
      "backupProductIds": ["987654321", "555555555"]
    }
  ],
  "fallbackUrl": "https://www.walmart.com/",
  "tracking": {
    "utm": {
      "source": "newsletter",
      "medium": "email",
      "campaign": "summer-grilling"
    },
    "tags": ["grilling", "q3"]
  }
}
```

### Product fields

| Field               | Type             | Required | Description                                                            |
| ------------------- | ---------------- | -------- | ---------------------------------------------------------------------- |
| `retailerProductId` | string           | Yes      | Walmart item ID.                                                       |
| `quantity`          | integer          | No       | Quantity to add (default: 1, max: 999).                                |
| `backupProductIds`  | array of strings | No       | Ordered backup item IDs tried when the primary is unavailable. Max 25. |

## Smart-select

Walmart smart-select resolves offers and may include a store ID in the generated cart URL. You can
send `location.storeId` when you already know the store to use, but it is not required for a basic
add-to-cart link.

Without a store hint, Walmart requests can still create a direct add-to-cart URL from the product
IDs you send.

```json theme={null}
{
  "projectId": "proj_123",
  "name": "Walmart store-aware cart",
  "retailer": "walmart",
  "intent": "add_to_cart",
  "location": {
    "storeId": "3520"
  },
  "products": [
    {
      "retailerProductId": "550098461",
      "quantity": 1,
      "backupProductIds": []
    }
  ],
  "options": {
    "walmart": {
      "allowPdp": true,
      "cartMode": "auto",
      "fallbackMode": "items",
      "includeStoreId": "auto"
    }
  }
}
```

### Walmart options

| Field                        | Type                          | Default | Description                                                                                     |
| ---------------------------- | ----------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `allowPdp`                   | boolean                       | `false` | Allow single-item links to resolve to a product page when cart construction is not appropriate. |
| `cartMode`                   | `auto` \| `offers` \| `items` | `auto`  | How to build the cart URL.                                                                      |
| `fallbackMode`               | `offers` \| `items`           | `items` | Fallback cart mode when the primary mode fails.                                                 |
| `includeStoreId`             | `never` \| `auto` \| `always` | `auto`  | Whether to include the store ID in the cart URL.                                                |
| `preferItemsForWalmart`      | boolean                       | `true`  | Prefer item-based URLs for Walmart-sold products.                                               |
| `preferOffersForMarketplace` | boolean                       | `false` | Prefer offer-based URLs for marketplace products.                                               |

The effective defaults are `fallbackMode: "items"`, `preferItemsForWalmart: true`, and
`preferOffersForMarketplace: false`. They match links created in the Incarts dashboard.

## Product detail

Use `intent: "product_detail"` with exactly one item when you want a tracked Walmart product page
instead of a cart.

```json theme={null}
{
  "projectId": "proj_123",
  "name": "Walmart product page",
  "retailer": "walmart",
  "intent": "product_detail",
  "products": [{ "retailerProductId": "550098461", "quantity": 1 }]
}
```

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