> ## Documentation Index
> Fetch the complete documentation index at: https://guides.affiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Create a named product list with one or more product IDs and optional metadata. Returns the new list ID and full product objects for every product added.

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

<ParamField header="Authorization" type="string" required>
  Your API key as a Bearer token: `Bearer {your_api_key}`.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

### Body parameters

<ParamField body="name" type="string" required>
  A display name for the list. Use something meaningful to your application — for example, `"Smart Home Devices"` or `"Summer Campaign Q3"`.
</ParamField>

<ParamField body="product_ids" type="string[]" required>
  An array of product ID strings to include in the list. Product IDs come from the Products API search results.
</ParamField>

<ParamField body="metadata" type="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.

  ```json theme={null}
  {
    "metadata": {
      "category": "tech_products",
      "campaign": "summer"
    }
  }
  ```
</ParamField>

<ParamField body="pool_id" type="integer">
  Optional pool identifier to scope the list within a specific product pool.
</ParamField>

## Example request

```bash cURL theme={null}
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.

```json theme={null}
{
  "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

<ResponseField name="data" type="object">
  The newly created list object.

  <Expandable title="data properties">
    <ResponseField name="data.id" type="string">
      Unique identifier for the list. Use this ID to retrieve, update, or delete the list.
    </ResponseField>

    <ResponseField name="data.name" type="string">
      The display name you provided when creating the list.
    </ResponseField>

    <ResponseField name="data.metadata" type="object">
      The key:value metadata pairs you provided, returned as a JSON object.
    </ResponseField>

    <ResponseField name="data.products_count" type="integer">
      Total number of products currently in the list.
    </ResponseField>

    <ResponseField name="data.products" type="array">
      Full product objects for each product in the list. See the product fields table below.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="meta properties">
    <ResponseField name="meta.trace_id" type="string">
      A unique identifier for this request. Include this value when contacting support.
    </ResponseField>
  </Expandable>
</ResponseField>

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