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

> Retrieve vendor-scoped fulfillment items 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 line items with their fulfillment status and tracking information, scoped to the authenticated vendor. Only line items belonging to the vendor are returned. Use this endpoint to monitor pending and completed fulfillments.

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

### Use Cases

* **Fulfillment dashboard** — Monitor pending and completed fulfillments for the vendor
* **Shipping integration** — Pull unfulfilled items for 3PL or warehouse systems
* **Order management** — Track the vendor's fulfillment queue

## Query Parameters

<ParamField query="fulfillmentStatus" type="string">
  Filter by fulfillment status. One of: `fulfilled`, `unfulfilled`.
</ParamField>

<ParamField query="shipmentStatus" type="string">
  Filter by shipment status (max 50 characters).
</ParamField>

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

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

<ParamField query="search" type="string">
  Search in order name/number or line item name (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": {
    "items": [
      {
        "_id": "507f1f77bcf86cd799439015",
        "orderId": 5123456789,
        "orderNumber": 1042,
        "orderName": "#1042",
        "lineItemName": "Widget Pro - Large / Blue",
        "lineItemSku": "WP-LG-BL",
        "quantity": 2,
        "fulfillment": {
          "status": "fulfilled",
          "trackingCompany": "Royal Mail",
          "trackingNumber": "RM123456789GB",
          "trackingUrl": "https://tracking.royalmail.com/RM123456789GB",
          "createdAt": "2024-06-16T09:00:00.000Z"
        },
        "shippingAddress": {
          "name": "Jane Doe",
          "address1": "123 High Street",
          "city": "London",
          "country": "United Kingdom",
          "zip": "SW1A 1AA"
        },
        "date": "2024-06-15T10:30:00.000Z"
      }
    ],
    "pageInfo": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "startCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxNSJ9",
      "endCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAyNSJ9",
      "totalCount": 85
    }
  }
}
```

## Example

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

### More Examples

**Filter unfulfilled items in date range**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/fulfillments?first=20&fulfillmentStatus=unfulfilled&dateMin=2026-05-01T00:00:00Z&sortBy=date&sortOrder=asc" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```

**Search by order number**

```bash theme={null}
curl -X GET "https://staging-api.puppetvendors.com/fulfillments?first=10&search=1042" \
  -H "x-access-token: YOUR_VENDOR_JWT_TOKEN"
```