# Product Lists

## Creates a new product list for a store, optionally including initial line items.

`product_lists.create_product_list(strstore_number, ProductListCreateProductListParams**kwargs)  -> ProductListCreateProductListResponse`

**post** `/api/v2/public/stores/{store_number}/productlists`

Creates a new product list for a store, optionally including initial line items.

### Parameters

- `store_number: str`

- `product_list_name: str`

  Name of the product list. Must contain only letters, numbers, spaces, dots, hyphens, or underscores.

- `product_list_type: int`

  Numeric product list type identifier. Ignored when `module_id` is supplied; the type is then resolved from the module.

- `app_username: Optional[str]`

  Name of the app user creating the product list. Defaults to "unknown" when omitted.

- `free_fields: Optional[Iterable[FreeField]]`

  Custom free-field key/value pairs to attach to the product list.

  - `key: Optional[str]`

    Free-field key.

  - `value: Optional[str]`

    Free-field value.

- `is_allow_duplicate_products: Optional[bool]`

  When true (default), duplicate products may appear on multiple lines. When false, lines for the same product are merged and quantities are summed.

- `lines: Optional[Iterable[Line]]`

  Initial line items to add to the product list. May be empty; lines may be added later via the line-update endpoint.

  - `product_number: str`

    Product number identifying which product the line refers to. Unknown product numbers are silently skipped.

  - `quantity: float`

    Quantity for the line. A value of 0 is treated as 1.

  - `barcode: Optional[str]`

    Ignored on input. The barcode stored on the line is sourced from the product master via `product_number`. Field retained for backwards compatibility.

- `module_id: Optional[int]`

  Optional module identifier. When set, the product list type is resolved from the module's configured type and `product_list_type` is ignored.

### Returns

- `class ProductListCreateProductListResponse: …`

  Response returned after a product list is created. Contains the identifier of the new list.

  - `product_list_id: int`

    Identifier of the newly created product list.

### Example

```python
import os
from colleqtive_sdk import Colleqtive

client = Colleqtive(
    bearer_token=os.environ.get("COLLEQTIVE_BEARER_TOKEN"),  # This is the default and can be omitted
)
response = client.product_lists.create_product_list(
    store_number="store_number",
    product_list_name="Produce",
    product_list_type=1,
    free_fields=[{
        "key": "department",
        "value": "produce",
    }],
    is_allow_duplicate_products=True,
    lines=[{
        "product_number": "PRD-001",
        "quantity": 5,
    }, {
        "product_number": "PRD-002",
        "quantity": 12,
    }],
)
print(response.product_list_id)
```

#### Response

```json
{
  "product_list_id": 0
}
```

## Retrieves a paginated list of product lists for a specific store, optionally including line items.

`product_lists.list_product_lists(strstore_number, ProductListListProductListsParams**kwargs)  -> ProductListListProductListsResponse`

**get** `/api/v2/public/stores/{store_number}/productlists`

Retrieves a paginated list of product lists for a specific store, optionally including line items.

### Parameters

- `store_number: str`

- `last_updated_on: Optional[Union[str, datetime]]`

  Filter product lists modified on or after this date.

- `name: Optional[str]`

  Optional product list name filter.

- `product_list_id: Optional[int]`

  Optional product list identifier to filter by.

- `show_lines: Optional[bool]`

  When true, includes the line items for each product list.

- `type: Optional[int]`

  Optional product list type filter.

### Returns

- `class ProductListListProductListsResponse: …`

  Generic paginated response wrapper.

  - `page_size: int`

    Maximum number of items returned per page.

  - `page_start: int`

    Current page number (1-based).

  - `total_count: int`

    Total number of records matching the query across all pages.

  - `list: Optional[List[List]]`

    Collection of items for the current page.

    - `id: int`

      Unique identifier of the product list.

    - `line_count: int`

      Number of line items on the product list.

    - `type: int`

      Numeric product list type identifier.

    - `app_username: Optional[str]`

      Name of the app user associated with the product list. Separate from the audit `created_by` / `modified_by` fields; this is the in-store app user the list belongs to.

    - `free_fields: Optional[List[ListFreeField]]`

      Custom free-field key/value pairs associated with the product list.

      - `key: Optional[str]`

        Free-field key.

      - `value: Optional[str]`

        Free-field value.

    - `lines: Optional[List[ListLine]]`

      Line items belonging to the product list. Only populated when `show_lines=true` is passed on the request.

      - `quantity: float`

        Quantity on the line.

      - `barcode: Optional[str]`

        The product barcode.

      - `category_code: Optional[str]`

        Category code of the product.

      - `colli: Optional[float]`

        Number of items per colli (case pack).

      - `is_decimal: Optional[bool]`

        Whether decimal quantities are allowed for the product.

      - `parent_category_code: Optional[str]`

        Parent category code of the product.

      - `product_name: Optional[str]`

        Display name of the product.

      - `product_number: Optional[str]`

        The product number.

      - `stock_pool: Optional[str]`

        Stock pool the line targets.

      - `store_walking_order: Optional[int]`

        Order in which the product appears in the store walking sequence.

    - `modified_on: Optional[datetime]`

      Date and time the product list was last modified.

    - `name: Optional[str]`

      Name of the product list.

    - `type_description: Optional[str]`

      Human-readable description of the product list type.

  - `list_body: Optional[Dict[str, Optional[object]]]`

    Additional body-level metadata for the list.

  - `list_filters: Optional[Dict[str, Optional[List[str]]]]`

    Active filter criteria applied to the result set, keyed by field name.

  - `next_page: Optional[int]`

    Next page number, or null when on the last page.

  - `previous_page: Optional[int]`

    Previous page number, or null when on the first page.

  - `project_last_modified_date: Optional[str]`

    Last modified date/time of the project.

  - `scroll_id: Optional[str]`

    Opaque scroll identifier for deep-pagination scenarios.

  - `server_time: Optional[str]`

    Server UTC date/time when the response was generated.

  - `sort_column: Optional[str]`

    Column name the results are sorted by.

  - `sort_order: Optional[str]`

    Sort direction (asc or desc).

  - `task_last_modified_date: Optional[str]`

    Last modified date/time of the task.

### Example

```python
import os
from colleqtive_sdk import Colleqtive

client = Colleqtive(
    bearer_token=os.environ.get("COLLEQTIVE_BEARER_TOKEN"),  # This is the default and can be omitted
)
response = client.product_lists.list_product_lists(
    store_number="store_number",
)
print(response.scroll_id)
```

#### Response

```json
{
  "page_size": 0,
  "page_start": 0,
  "total_count": 0,
  "list": [
    {
      "id": 0,
      "line_count": 0,
      "type": 0,
      "app_username": "app_username",
      "free_fields": [
        {
          "key": "key",
          "value": "value"
        }
      ],
      "lines": [
        {
          "quantity": 0,
          "barcode": "barcode",
          "category_code": "category_code",
          "colli": 0,
          "is_decimal": true,
          "parent_category_code": "parent_category_code",
          "product_name": "product_name",
          "product_number": "product_number",
          "stock_pool": "stock_pool",
          "store_walking_order": 0
        }
      ],
      "modified_on": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "type_description": "type_description"
    }
  ],
  "list_body": {
    "foo": "bar"
  },
  "list_filters": {
    "foo": [
      "string"
    ]
  },
  "next_page": 0,
  "previous_page": 0,
  "project_last_modified_date": "project_last_modified_date",
  "scroll_id": "scroll_id",
  "server_time": "server_time",
  "sort_column": "sort_column",
  "sort_order": "sort_order",
  "task_last_modified_date": "task_last_modified_date"
}
```

## Deletes a product list by id, optionally archiving it or removing only its header.

`product_lists.delete_product_list(strstore_number, ProductListDeleteProductListParams**kwargs)  -> ProductListDeleteProductListResponse`

**delete** `/api/v2/public/stores/{store_number}/productlists`

Deletes a product list by id, optionally archiving it or removing only its header.

### Parameters

- `store_number: str`

- `product_list_id: int`

  The product list identifier to delete.

- `is_archived: Optional[bool]`

  When true, archives the product list instead of permanently deleting it.

- `is_delete_header: Optional[bool]`

  When true, deletes only the product list header (and its lines).

- `accept_language: Optional[str]`

- `api_key: Optional[str]`

### Returns

- `bool`

### Example

```python
import os
from colleqtive_sdk import Colleqtive

client = Colleqtive(
    bearer_token=os.environ.get("COLLEQTIVE_BEARER_TOKEN"),  # This is the default and can be omitted
)
response = client.product_lists.delete_product_list(
    store_number="store_number",
    product_list_id=0,
)
print(response)
```

#### Response

```json
true
```

## Adds or updates lines on an existing product list.

`product_lists.update_product_list_lines(intid, ProductListUpdateProductListLinesParams**kwargs)  -> ProductListUpdateProductListLinesResponse`

**post** `/api/v2/public/stores/{store_number}/productlists/{id}`

Adds or updates lines on an existing product list.

### Parameters

- `store_number: str`

- `id: int`

- `lines: Optional[Iterable[Line]]`

  The product list lines to add or update.

  - `quantity: float`

    Quantity on the line.

  - `article_no: Optional[str]`

    Deprecated. Use `product_number` instead. Still accepted on input for backwards compatibility.

  - `barcode: Optional[str]`

    The product barcode.

  - `product_number: Optional[str]`

    Product number identifying the line item.

  - `stock_pool: Optional[str]`

    Stock pool the line targets.

- `api_key: Optional[str]`

### Returns

- `class ProductListUpdateProductListLinesResponse: …`

  - `code: Optional[int]`

  - `data: Optional[str]`

  - `message: Optional[str]`

  - `status: Optional[str]`

### Example

```python
import os
from colleqtive_sdk import Colleqtive

client = Colleqtive(
    bearer_token=os.environ.get("COLLEQTIVE_BEARER_TOKEN"),  # This is the default and can be omitted
)
response = client.product_lists.update_product_list_lines(
    id=0,
    store_number="store_number",
    lines=[{
        "product_number": "PRD-001",
        "stock_pool": "StoreStockPool1",
        "quantity": 5,
    }, {
        "product_number": "PRD-002",
        "stock_pool": "StoreStockPool1",
        "quantity": 12,
    }],
)
print(response.code)
```

#### Response

```json
{
  "code": 0,
  "data": "data",
  "message": "message",
  "status": "status"
}
```

## Domain Types

### Product List Create Product List Response

- `class ProductListCreateProductListResponse: …`

  Response returned after a product list is created. Contains the identifier of the new list.

  - `product_list_id: int`

    Identifier of the newly created product list.

### Product List List Product Lists Response

- `class ProductListListProductListsResponse: …`

  Generic paginated response wrapper.

  - `page_size: int`

    Maximum number of items returned per page.

  - `page_start: int`

    Current page number (1-based).

  - `total_count: int`

    Total number of records matching the query across all pages.

  - `list: Optional[List[List]]`

    Collection of items for the current page.

    - `id: int`

      Unique identifier of the product list.

    - `line_count: int`

      Number of line items on the product list.

    - `type: int`

      Numeric product list type identifier.

    - `app_username: Optional[str]`

      Name of the app user associated with the product list. Separate from the audit `created_by` / `modified_by` fields; this is the in-store app user the list belongs to.

    - `free_fields: Optional[List[ListFreeField]]`

      Custom free-field key/value pairs associated with the product list.

      - `key: Optional[str]`

        Free-field key.

      - `value: Optional[str]`

        Free-field value.

    - `lines: Optional[List[ListLine]]`

      Line items belonging to the product list. Only populated when `show_lines=true` is passed on the request.

      - `quantity: float`

        Quantity on the line.

      - `barcode: Optional[str]`

        The product barcode.

      - `category_code: Optional[str]`

        Category code of the product.

      - `colli: Optional[float]`

        Number of items per colli (case pack).

      - `is_decimal: Optional[bool]`

        Whether decimal quantities are allowed for the product.

      - `parent_category_code: Optional[str]`

        Parent category code of the product.

      - `product_name: Optional[str]`

        Display name of the product.

      - `product_number: Optional[str]`

        The product number.

      - `stock_pool: Optional[str]`

        Stock pool the line targets.

      - `store_walking_order: Optional[int]`

        Order in which the product appears in the store walking sequence.

    - `modified_on: Optional[datetime]`

      Date and time the product list was last modified.

    - `name: Optional[str]`

      Name of the product list.

    - `type_description: Optional[str]`

      Human-readable description of the product list type.

  - `list_body: Optional[Dict[str, Optional[object]]]`

    Additional body-level metadata for the list.

  - `list_filters: Optional[Dict[str, Optional[List[str]]]]`

    Active filter criteria applied to the result set, keyed by field name.

  - `next_page: Optional[int]`

    Next page number, or null when on the last page.

  - `previous_page: Optional[int]`

    Previous page number, or null when on the first page.

  - `project_last_modified_date: Optional[str]`

    Last modified date/time of the project.

  - `scroll_id: Optional[str]`

    Opaque scroll identifier for deep-pagination scenarios.

  - `server_time: Optional[str]`

    Server UTC date/time when the response was generated.

  - `sort_column: Optional[str]`

    Column name the results are sorted by.

  - `sort_order: Optional[str]`

    Sort direction (asc or desc).

  - `task_last_modified_date: Optional[str]`

    Last modified date/time of the task.

### Product List Delete Product List Response

- `bool`

### Product List Update Product List Lines Response

- `class ProductListUpdateProductListLinesResponse: …`

  - `code: Optional[int]`

  - `data: Optional[str]`

  - `message: Optional[str]`

  - `status: Optional[str]`