Create links

Create shoppable retailer links for supported Incarts intents

Create a link with POST /v1/links. The API accepts a shared request body plus retailer-specific options.

A successful request returns the link resource, a shareable short link, and default QR code metadata.

Supported intents

Intent	Retailer	Status	Main requirement
custom_url	Any	Available	Provide customUrl.
add_to_cart	walmart	Available	Provide at least one product.
product_detail	target	Coming soon	Provide at least one product.
shopping_list	instacart	Available with Instacart scope	Provide options.instacart.shoppingList.
recipe	instacart	Available with Instacart scope	Provide options.instacart.recipe.

Walmart and Target requests without a ZIP code generate links from the provided product IDs only.

Request shape

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

{
  "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"]
  }
}

Walmart smart-select

Include location.zipCode and optionally location.storeId to use Walmart smart-select. Smart-select may return an add-to-cart URL with resolved offers and a store ID.

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

Response

Successful creation returns 201 with a data object containing the link ID, status, target URL, short link, and default QR code.

Create link endpoint

See request fields, examples, and response codes.