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

# Product Lists API: save and manage product sets

> Store named product collections in Affiliate.com without managing your own database. Tag lists with metadata and retrieve full product data on demand.

The Product Lists API lets you persist curated sets of product IDs in Affiliate.com's infrastructure and retrieve them — along with live product data — at any time. You don't need to run your own database to save, label, or share product collections.

## What you can do with Product Lists

* **Save search results** — run a product search, then persist the result IDs to a named list for later use.
* **Curate editorial collections** — build hand-picked sets for landing pages, gift guides, or seasonal promotions.
* **Power recommendation widgets** — store personalised or algorithmic product sets and fetch fresh product data on each page load.
* **Share product sets** — create lists scoped to a campaign or category and retrieve them by metadata key:value pairs.

## Metadata

Every list supports up to **16 key:value pairs** of metadata that you define. You can use metadata to label lists by campaign, category, author, season, or any other dimension that matters to your application.

* Key maximum length: **64 characters**
* Value maximum length: **512 characters**
* Filter by metadata at query time using `?metadata[key]=value`

```
GET /v1/products/lists?metadata[category]=tech_products&metadata[campaign]=summer
```

Metadata values are returned in every list response so you can use them programmatically.

## How list contents work

A list stores **product IDs**. Retrieving a list with `GET /v1/products/lists/{list_id}` returns the current full product objects for each stored ID — prices, availability, images, affiliate URLs, and all other fields — reflecting the latest data from the merchant feed.

<Note>
  `GET /v1/products/lists` returns list summaries only: name, `products_count`, and metadata. It does **not** return product details. Use `GET /v1/products/lists/{list_id}` to retrieve the full product data for a specific list.
</Note>

## Available endpoints

| Method   | Endpoint                                 | Description                              |
| -------- | ---------------------------------------- | ---------------------------------------- |
| `POST`   | `/v1/products/lists`                     | Create a new list with products          |
| `GET`    | `/v1/products/lists`                     | Get all your lists (summaries only)      |
| `GET`    | `/v1/products/lists/{list_id}`           | Get a single list with full product data |
| `GET`    | `/v1/products/lists?metadata[key]=value` | Filter lists by metadata                 |
| `POST`   | `/v1/products/lists/{list_id}/items`     | Add products to an existing list         |
| `DELETE` | `/v1/products/lists/{list_id}/products`  | Remove products from a list              |
| `DELETE` | `/v1/products/lists/{list_id}`           | Permanently delete a list                |