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

# List Shipments

> List all shipments with filtering and pagination

<Note>
  This endpoint retrieves a paginated list of shipments. Use filters to narrow results by status, date range, carrier, and more.
</Note>

## Authentication

This endpoint requires a valid API key with `shipments:read` permissions.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="integer">
  Number of items to return (default: 20, max: 100)
</ParamField>

<ParamField query="offset" type="integer">
  Number of items to skip
</ParamField>

<ParamField query="status" type="string">
  Filter by status: "label\_created", "picked\_up", "in\_transit", "out\_for\_delivery", "delivered", "returned", "failed"
</ParamField>

<ParamField query="carrier" type="string">
  Filter by carrier: "ups", "fedex", "usps", "dhl"
</ParamField>

<ParamField query="warehouse_id" type="string">
  Filter by origin warehouse
</ParamField>

<ParamField query="order_id" type="string">
  Filter by associated order
</ParamField>

<ParamField query="tracking_number" type="string">
  Filter by tracking number
</ParamField>

<ParamField query="ship_date_from" type="string">
  Filter by ship date start (ISO 8601)
</ParamField>

<ParamField query="ship_date_to" type="string">
  Filter by ship date end (ISO 8601)
</ParamField>

<ParamField query="delivery_date_from" type="string">
  Filter by delivery date start (ISO 8601)
</ParamField>

<ParamField query="delivery_date_to" type="string">
  Filter by delivery date end (ISO 8601)
</ParamField>

<ParamField query="destination_country" type="string">
  Filter by destination country code
</ParamField>

<ParamField query="destination_state" type="string">
  Filter by destination state/province
</ParamField>

<ParamField query="sort_by" type="string">
  Sort field: "created\_at", "ship\_date", "delivery\_date", "status"
</ParamField>

<ParamField query="sort_order" type="string">
  Sort order: "asc" or "desc" (default: "desc")
</ParamField>

### Response

<ResponseField name="object" type="string">
  Object type, always "list"
</ResponseField>

<ResponseField name="data" type="array">
  Array of shipment objects
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more items exist
</ResponseField>

<ResponseField name="total_count" type="integer">
  Total number of matching shipments
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/shipments?status=in_transit&limit=10' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const shipments = await stateset.shipments.list({
    status: 'in_transit',
    limit: 10,
    sort_by: 'ship_date',
    sort_order: 'desc'
  });
  ```

  ```python Python theme={null}
  shipments = stateset.shipments.list(
    status='in_transit',
    limit=10,
    sort_by='ship_date',
    sort_order='desc'
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
        "object": "shipment",
        "status": "in_transit",
        "created_at": "2024-01-19T14:30:00Z",
        "ship_date": "2024-01-20T08:00:00Z",
        "delivery_date": "2024-01-23T18:00:00Z",
        "carrier": "ups",
        "service_type": "ground",
        "tracking_number": "1Z999AA10123456784",
        "tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
        "packages_count": 1,
        "total_weight": {
          "value": 5.5,
          "unit": "lb"
        },
        "from_address": {
          "city": "Los Angeles",
          "state": "CA",
          "country": "US"
        },
        "to_address": {
          "name": "John Doe",
          "city": "Los Angeles",
          "state": "CA",
          "country": "US"
        },
        "order_ids": ["order_123456", "order_123457"],
        "rate": {
          "amount": 1250,
          "currency": "USD"
        }
      },
      {
        "id": "ship_7823f083-bb2c-54d6-bf6d-1b8e3fc75f41",
        "object": "shipment",
        "status": "in_transit",
        "created_at": "2024-01-19T10:15:00Z",
        "ship_date": "2024-01-19T14:00:00Z",
        "delivery_date": "2024-01-22T18:00:00Z",
        "carrier": "fedex",
        "service_type": "express",
        "tracking_number": "772123456789",
        "tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=772123456789",
        "packages_count": 2,
        "total_weight": {
          "value": 12.3,
          "unit": "lb"
        },
        "from_address": {
          "city": "New York",
          "state": "NY",
          "country": "US"
        },
        "to_address": {
          "name": "Jane Smith",
          "city": "Chicago",
          "state": "IL",
          "country": "US"
        },
        "order_ids": ["order_789012"],
        "rate": {
          "amount": 2850,
          "currency": "USD"
        }
      }
    ],
    "has_more": true,
    "total_count": 156,
    "page_info": {
      "limit": 10,
      "offset": 0
    }
  }
  ```
</ResponseExample>