> ## 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 fulfillment data for line items

## Overview

Returns a paginated list of line items with their fulfillment status, tracking info, and shipping/billing addresses. Only items with `"paid"` financial status are included.

### Use Cases

* **Monitor fulfillment progress** across all vendors
* **Build a shipping dashboard** showing tracking numbers and carriers
* **Identify unfulfilled orders** that need attention
* **Export fulfillment data** for logistics reporting
* **Track shipment statuses** (in\_transit, delivered, etc.)

## Query Parameters

<ParamField query="vendorId" type="string">
  Filter by vendor ID.
</ParamField>

<ParamField query="start" type="string">
  Start date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="end" type="string">
  End date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="fulfillment" type="string">
  Filter: `"fulfilled"` or `"unfulfilled"`.
</ParamField>

<ParamField query="shipment" type="string">
  Filter by shipment status (e.g. `"in_transit"`, `"delivered"`).
</ParamField>

<ParamField query="limit" type="number">
  Results per page. Default: `100`.
</ParamField>

<ParamField query="offset" type="number">
  Number of results to skip. Default: `0`.
</ParamField>

## Response

```json 200 theme={null}
{
  "total": 42,
  "nextOffset": null,
  "fulfillments": [
    {
      "_id": "...",
      "orderNumber": 1042,
      "orderName": "#1042",
      "date": "2024-03-15T00:00:00.000Z",
      "vendorId": "...",
      "vendorName": "acme supplies",
      "lineItemName": "Classic T-Shirt - Large",
      "lineItemVariant": "Large / Blue",
      "lineItemSku": "TSH-LG-BLU",
      "fulfillment": {
        "status": "success",
        "trackingCompany": "Royal Mail",
        "trackingNumber": "RM123456789GB",
        "trackingUrl": "https://tracking.royalmail.com/...",
        "createdAt": "2024-03-16T10:00:00.000Z"
      },
      "shippingAddress": {
        "first_name": "John",
        "last_name": "Doe",
        "address1": "10 Downing Street",
        "city": "London",
        "country": "United Kingdom"
      }
    }
  ]
}
```

## Example

```bash theme={null}
# Unfulfilled items for a vendor
curl -X GET "https://api.puppetvendors.com/v1/fulfillments?vendorId=6157fa...&fulfillment=unfulfilled" \
  -H "x-access-token: YOUR_JWT_TOKEN"
```