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

# List Products

> Retrieve vendor-scoped products with cursor-based pagination

<Note>
  **V2 Alpha** — This endpoint is part of the V2 API preview. Breaking changes may occur.
</Note>

## Overview

Retrieve a paginated list of products belonging to the authenticated vendor. Results include product title, handle, status, variants, and images. Only products assigned to the vendor are returned.

<Note>
  **Vendor Token Required** — This endpoint requires a vendor-scoped JWT token. Merchant tokens will receive a 403 error.
</Note>

### Use Cases

* **Product catalogue** — Display a vendor's product listings in a custom portal
* **Inventory management** — Pull product data for stock-level monitoring
* **Product sync** — Export vendor products to external systems

## Query Parameters

<ParamField query="status" type="string">
  Filter by product status. One of: `active`, `draft`, `archived`.
</ParamField>

<ParamField query="createdAtMin" type="string">
  Filter by creation date (minimum, ISO 8601). Example: `2024-01-01T00:00:00Z`.
</ParamField>

<ParamField query="createdAtMax" type="string">
  Filter by creation date (maximum, ISO 8601).
</ParamField>

<ParamField query="search" type="string">
  Search in product title or handle (max 200 characters).
</ParamField>

<ParamField query="first" type="integer">
  Number of items to return, forward pagination (1-100).
</ParamField>

<ParamField query="after" type="string">
  Cursor for forward pagination.
</ParamField>

<ParamField query="last" type="integer">
  Number of items to return, backward pagination (1-100).
</ParamField>

<ParamField query="before" type="string">
  Cursor for backward pagination.
</ParamField>

## Response

```json 200 theme={null}
{
  "success": true,
  "data": {
    "products": [
      {
        "_id": "507f1f77bcf86cd799439030",
        "title": "Widget Pro",
        "handle": "widget-pro",
        "status": "active",
        "productId": 7654321098765,
        "variants": [
          {
            "variantId": 43210987654321,
            "title": "Small",
            "price": "19.99",
            "sku": "WP-SM",
            "inventoryQuantity": 50
          },
          {
            "variantId": 43210987654322,
            "title": "Medium",
            "price": "24.99",
            "sku": "WP-MD",
            "inventoryQuantity": 30
          }
        ],
        "images": [
          {
            "src": "https://cdn.shopify.com/s/files/1/example/widget-pro.jpg",
            "alt": "Widget Pro main image"
          }
        ],
        "createdAt": "2024-06-10T08:00:00.000Z"
      }
    ],
    "totalCount": 42,
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAzMCJ9",
      "endCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTA0MCJ9"
    }
  }
}
```

## Example

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/products?status=active&first=20" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```

### More Examples

**Filter active products sorted by inventory**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/products?first=50&status=active&sortBy=totalInventory&sortOrder=asc" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```

**Search out-of-stock products**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/products?first=20&search=summer+collection&inventoryStatus=outOfStock" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```