Create a shoppable link

curl --request POST \
  --url https://incarts-api-qob6vapoca-uc.a.run.app/v1/links \
  --header 'Content-Type: application/json' \
  --header 'X-Incarts-API-Key: <api-key>' \
  --data '
{
  "projectId": "proj_123",
  "name": "Summer grilling basket",
  "retailer": "walmart",
  "intent": "add_to_cart",
  "products": [
    {
      "retailerProductId": "123456789",
      "quantity": 1,
      "backupProductIds": [
        "987654321",
        "555555555"
      ]
    }
  ],
  "options": {
    "walmart": {
      "allowPdp": true,
      "cartMode": "auto",
      "fallbackMode": "items",
      "includeStoreId": "auto"
    }
  }
}
'

{
  "data": {
    "id": "lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9",
    "projectId": "proj_123",
    "name": "Summer grilling basket",
    "publicName": "Shop the grilling list",
    "retailer": "walmart",
    "intent": "add_to_cart",
    "status": "active",
    "shortLink": "https://in2carts.com/abc123",
    "shortId": "abc123",
    "qrCode": {
      "id": "qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default",
      "linkId": "lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9",
      "identifier": "default",
      "name": "Default QR code",
      "imageUrl": "https://firebasestorage.googleapis.com/v0/b/incarts.appspot.com/o/qrcodes%2Fexample.png?alt=media",
      "encodedUrl": "https://in2carts.com/qr/qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default",
      "isDefault": true,
      "createdAt": "2026-05-20T07:19:00Z"
    },
    "createdAt": "2026-05-20T07:19:00Z"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "unsupported_retailer_intent",
    "message": "Kroger add-to-cart links are not supported.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

POST

https://incarts-api-qob6vapoca-uc.a.run.app

links

curl --request POST \
  --url https://incarts-api-qob6vapoca-uc.a.run.app/v1/links \
  --header 'Content-Type: application/json' \
  --header 'X-Incarts-API-Key: <api-key>' \
  --data '
{
  "projectId": "proj_123",
  "name": "Summer grilling basket",
  "retailer": "walmart",
  "intent": "add_to_cart",
  "products": [
    {
      "retailerProductId": "123456789",
      "quantity": 1,
      "backupProductIds": [
        "987654321",
        "555555555"
      ]
    }
  ],
  "options": {
    "walmart": {
      "allowPdp": true,
      "cartMode": "auto",
      "fallbackMode": "items",
      "includeStoreId": "auto"
    }
  }
}
'

{
  "data": {
    "id": "lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9",
    "projectId": "proj_123",
    "name": "Summer grilling basket",
    "publicName": "Shop the grilling list",
    "retailer": "walmart",
    "intent": "add_to_cart",
    "status": "active",
    "shortLink": "https://in2carts.com/abc123",
    "shortId": "abc123",
    "qrCode": {
      "id": "qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default",
      "linkId": "lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9",
      "identifier": "default",
      "name": "Default QR code",
      "imageUrl": "https://firebasestorage.googleapis.com/v0/b/incarts.appspot.com/o/qrcodes%2Fexample.png?alt=media",
      "encodedUrl": "https://in2carts.com/qr/qr_lnk_01JZ4TDK6A0NV2HG6R3Q7E28Y9_default",
      "isDefault": true,
      "createdAt": "2026-05-20T07:19:00Z"
    },
    "createdAt": "2026-05-20T07:19:00Z"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "unsupported_retailer_intent",
    "message": "Kroger add-to-cart links are not supported.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B"
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

{
  "error": {
    "code": "validation_failed",
    "message": "products is required for walmart add_to_cart links.",
    "correlationId": "req_01JZ4TCZ7AG9P9W38V4VNQ7W4B",
    "details": [
      {
        "field": "products",
        "message": "At least one product is required."
      }
    ]
  }
}

This endpoint accepts multiple request shapes for Amazon, Kroger, Walmart, Target, Instacart, and custom URLs. Use the Body tabs to switch schemas and the example dropdown above the code panel to load a pre-filled request.

Authorizations

X-Incarts-API-Key

string

header

required

Headers

Idempotency-Key

string

Stable client-generated key used to safely retry write requests.

Required string length: 8 - 128

X-Correlation-ID

string

Client-supplied request correlation ID. The API echoes this value when provided.

Required string length: 8 - 128

Body

application/json

Request body for creating a shoppable link. Choose the variant that matches the retailer and link type you want to create.

projectId

string

required

Project that owns the link.

Required string length: 1 - 128

Example:

"proj_123"

name

string

required

Internal name for the link, shown in your dashboards.

Required string length: 1 - 160

Example:

"Summer grilling basket"

retailer

enum<string>

required

Link provider used for generation.

Available options:

walmart

intent

enum<string>

required

Creates a Walmart add-to-cart link.

Available options:

add_to_cart

products

object[]

required

Retailer product selections for product and cart style links.

Required array length: 1 - 100 elements

Show child attributes

publicName

string

Optional display name for public surfaces.

Required string length: 1 - 160

Example:

"Shop the grilling list"

customUrl

string<uri>

Destination URL for custom_url links.

Example:

"https://www.example.com/landing-page"

fallbackUrl

string<uri>

Fallback destination used when a better retailer URL can't be built.

Example:

"https://www.walmart.com/"

location

object

Show child attributes

options

object

Show child attributes

tracking

object

Show child attributes

metadata

object

Caller-supplied metadata stored with the resource. Do not put secrets here.

Example:

{ "campaignId": "cmp_123" }

defaultQrCode

object

Show child attributes

Response

Link created.

data

object

required

Show child attributes

Check service readiness Find supported retailers

Overview

Endpoints

Create a shoppable link

Authorizations

Headers

Body

Response