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

# 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 always returns the link resource and shareable short link. It includes default
QR metadata when QR generation succeeds.

## Supported intents

| Intent           | Retailer    | Status                         | Main requirement                                                                                           |
| ---------------- | ----------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `add_to_cart`    | `amazon`    | Available                      | Provide one or more Amazon ASINs.                                                                          |
| `product_detail` | `amazon`    | Available                      | Provide exactly one Amazon ASIN.                                                                           |
| `product_detail` | `kroger`    | Available                      | Provide exactly one Kroger product ID.                                                                     |
| `add_to_cart`    | `walmart`   | Available                      | Provide at least one product.                                                                              |
| `product_detail` | `walmart`   | Available                      | Provide exactly one Walmart item ID.                                                                       |
| `add_to_cart`    | `target`    | Available                      | Provide one or more Target TCINs.                                                                          |
| `product_detail` | `target`    | Available                      | Provide one or more Target TCINs.                                                                          |
| `product_detail` | `instacart` | Available with Instacart scope | Provide exactly one Instacart product ID and send `options.instacart.retailer` for retailer-specific PDPs. |
| `shopping_list`  | `instacart` | Available with Instacart scope | Provide `options.instacart.shoppingList`.                                                                  |
| `recipe`         | `instacart` | Available with Instacart scope | Provide `options.instacart.recipe`.                                                                        |
| `custom_url`     | `custom`    | Available                      | Provide `customUrl`.                                                                                       |

## Shared request fields

Every link request includes these top-level fields. Retailer-specific options go inside `options`.

| Field           | Type         | Required | Description                                                                             |
| --------------- | ------------ | -------- | --------------------------------------------------------------------------------------- |
| `projectId`     | string       | Yes      | Project that owns the link.                                                             |
| `name`          | string       | Yes      | Internal name shown in dashboards.                                                      |
| `publicName`    | string       | No       | Display name for public surfaces.                                                       |
| `retailer`      | string       | Yes      | Link provider: `amazon`, `kroger`, `walmart`, `target`, `instacart`, or `custom`.       |
| `intent`        | string       | Yes      | Link type: `add_to_cart`, `shopping_list`, `recipe`, `product_detail`, or `custom_url`. |
| `fallbackUrl`   | string (URI) | No       | Fallback destination when a better retailer URL can't be built.                         |
| `tracking`      | object       | No       | UTM parameters, link value, and tags.                                                   |
| `metadata`      | object       | No       | Caller-supplied key-value metadata stored with the link.                                |
| `defaultQrCode` | object       | No       | Customize the identifier and name of the best-effort default QR code.                   |

## Retailer discovery

Use `GET /v1/retailers` to find supported Instacart stores before creating Instacart links.
The endpoint returns the `retailerId` values used by shopping list and recipe links, plus the slug
used by Instacart product detail links.

## Response

Successful creation returns `201` with a `data` object containing the link ID, status, and shareable
`shortLink`. The optional `qrCode` field is present when default QR generation succeeds.

The API attempts to create the default QR image and persist it atomically with the link. If QR
generation or the QR write fails, it falls back to persisting and returning the link without
`qrCode`. You can retry QR creation later with the QR endpoint.

The final retailer destination URL is not returned in the response. Incarts keeps that URL behind
the short link so shoppers use the shoppable Incarts link you receive from the API.

## Retailer guides

<CardGroup cols={2}>
  <Card title="Direct retailer links" icon="bag-shopping" href="/guides/direct-retailer-links">
    Amazon, Kroger, Target, and Walmart direct cart or product links.
  </Card>

  <Card title="Instacart links" icon="cart-shopping" href="/guides/instacart-links">
    Product detail links, shopping lists, recipes, and retailer routing.
  </Card>

  <Card title="Walmart links" icon="store" href="/guides/walmart-links">
    Add-to-cart, product detail, backups, and smart-select.
  </Card>

  <Card title="Custom URL links" icon="link" href="/guides/custom-links">
    Wrap any URL in a trackable Incarts short link.
  </Card>

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

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