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

# Product List Items

> Adding, updating, and removing items from a product list via the Omneo API.

A Product List is a collection of List Items. Each item references either a product from the Omneo product catalogue or a custom user-defined product.

## Adding an item from the Omneo product catalogue

Provide at least one product identifier (`product_variant_id`, `product_id`, `product_variant_sku`, `product_variant_barcode`, or `external_id`):

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/profiles/{profileId}/lists/{listId}/items \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_variant_id": 333729,
    "quantity": 1,
    "position": 1
  }'
```

To include quantity, the List Definition must have `allow_quantity: true`.

## Adding items when creating a list

Items can be included inline in the list creation payload:

```json theme={null}
{
  "name": "Birthday Wishlist",
  "list_definition_id": 3,
  "items": [
    {
      "product_variant_id": 333729,
      "quantity": 1,
      "position": 1
    }
  ]
}
```

## Adding a custom product item

If the List Definition has `allow_custom_product: true`, you can add items not in the Omneo product catalogue:

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/profiles/{profileId}/lists/{listId}/custom \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Vintage Chanel Bag",
    "description": "Seen at the vintage market",
    "price": 450.00,
    "currency": "AUD",
    "url": "https://example.com/item",
    "image_url": "https://example.com/item.jpg",
    "quantity": 1
  }'
```

## Removing a list item

```shell theme={null}
DELETE /api/v3/profiles/{profileId}/lists/{listId}/items/{itemId}
```

## Updating item position or quantity

Update is done on the list level. Include the item's `id` in the `items` array of a PUT request to the list:

```shell theme={null}
curl -X PUT https://api.[tenant].getomneo.com/api/v3/profiles/{profileId}/lists/{listId} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "item-uuid", "quantity": 2, "position": 1 }
    ]
  }'
```