POST /v1/products/lists — create a product list

Use POST /v1/products/lists to create a new product list. Provide a name, one or more product IDs, and any metadata key:value pairs you want to associate with the list. The response returns the new list ID together with full product objects for every product you included.

Request

Endpoint: POST /v1/products/lists

Headers

string

required

Your API key as a Bearer token: Bearer {your_api_key}.

string

required

Must be application/json.

Body parameters

string

required

A display name for the list. Use something meaningful to your application — for example, "Smart Home Devices" or "Summer Campaign Q3".

string[]

required

An array of product ID strings to include in the list. Product IDs come from the Products API search results.

object

Up to 16 key:value string pairs you can use to label and query this list. Keys are max 64 characters; values are max 512 characters.

{
  "metadata": {
    "category": "tech_products",
    "campaign": "summer"
  }
}

integer

Optional pool identifier to scope the list within a specific product pool.

Example request

cURL

curl --request POST \
  --url https://api.affiliate.com/v1/products/lists \
  --header 'Authorization: Bearer {your_api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Smart Home Devices",
    "product_ids": [
      "1234567890123456789",
      "2345678901234567890"
    ],
    "metadata": {
      "category": "tech_products"
    },
    "pool_id": 456
  }'

Response

A 201 Created response contains a data object with the new list and full product details, plus a meta object with a trace ID.

{
  "data": {
    "id": "d345e67f-89g0-1h2i-3j45-6k7891lm2345",
    "name": "Smart Home Devices",
    "metadata": {
      "category": "tech_products"
    },
    "products_count": 2,
    "products": [
      {
        "id": "1234567890123456789",
        "barcode": 123456,
        "name": "Smart Thermostat Pro",
        "description": "Wi-Fi enabled thermostat with voice control",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-thermostat-pro",
        "direct_url": "https://www.example-store.com/products/smart-thermostat-pro",
        "image_url": "https://assets.example-store.com/images/products/thermostat-pro.jpg",
        "currency": "USD",
        "regular_price": 129.99,
        "final_price": 99.99,
        "on_sale": true,
        "sale_discount": 23,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SmartHome",
        "category": "Home & Garden > Smart Home > Climate Control",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      },
      {
        "id": "2345678901234567890",
        "barcode": 123456,
        "name": "Smart Security Camera",
        "description": "1080p HD security camera with night vision",
        "commission_url": "https://www.example-affiliate.net/click-123-456789?url=https%3A%2F%2Fwww.example-store.com%2Fproducts%2Fsmart-security-camera",
        "direct_url": "https://www.example-store.com/products/smart-security-camera",
        "image_url": "https://assets.example-store.com/images/products/security-camera.jpg",
        "currency": "USD",
        "regular_price": 89.99,
        "final_price": 89.99,
        "on_sale": false,
        "sale_discount": 0,
        "availability": "In Stock",
        "sku": 123456,
        "brand": "SecureTech",
        "category": "Home & Garden > Smart Home > Security",
        "network": {
          "id": 5,
          "name": "AffiliateNetwork",
          "logo_url": "https://img.affiliate.com/logos/networks/5/logo.png"
        },
        "merchant": {
          "id": 1234,
          "name": "Example Store",
          "logo_url": "https://img.affiliate.com/logos/merchants/1234/logo.png"
        }
      }
    ]
  },
  "meta": {
    "trace_id": "a98b7c65-4d32-1e0f-9g87-6h5432i10j9k"
  }
}

Response fields

object

The newly created list object.

Show data properties

string

Unique identifier for the list. Use this ID to retrieve, update, or delete the list.

string

The display name you provided when creating the list.

object

The key:value metadata pairs you provided, returned as a JSON object.

integer

Total number of products currently in the list.

array

Full product objects for each product in the list. See the product fields table below.

object

Show meta properties

string

A unique identifier for this request. Include this value when contacting support.

Product object fields

Each item in data.products contains the following fields.

Field	Type	Description
`id`	string	Unique product identifier
`barcode`	integer	UPC, EAN, or GTIN barcode
`name`	string	Product title
`description`	string	Full product description
`commission_url`	string	Affiliate URL — earn commission when customers purchase through this link
`direct_url`	string	Direct merchant URL (no commission)
`image_url`	string	Primary product image URL
`currency`	string	ISO 4217 currency code (e.g., `USD`)
`regular_price`	number	Original retail price
`final_price`	number	Current price after any discounts
`on_sale`	boolean	`true` when a sale discount is active
`sale_discount`	integer	Discount percentage
`availability`	string	Stock status (e.g., `In Stock`)
`sku`	integer	Merchant stock-keeping unit
`brand`	string	Brand name
`category`	string	Hierarchical category path
`network.id`	integer	Affiliate network ID
`network.name`	string	Affiliate network name
`network.logo_url`	string	Network logo URL
`merchant.id`	integer	Merchant ID
`merchant.name`	string	Merchant display name
`merchant.logo_url`	string	Merchant logo URL

Account

Networks

Merchants

Products

Tools

Watches

Product Lists

Pools

Reports

POST /v1/products/lists — create a product list

Request

Headers

Body parameters

Example request

Response

Response fields

Product object fields

​Request

​Headers

​Body parameters

​Example request

​Response

​Response fields

​Product object fields

Request

Headers

Body parameters

Example request

Response

Response fields

Product object fields