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

# Get Shipment

> Retrieve a specific shipment by ID

<Note>
  This endpoint retrieves detailed information about a specific shipment including tracking, packages, and delivery status.
</Note>

## Authentication

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

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

## Path Parameters

<ParamField path="id" type="string" required>
  The unique identifier of the shipment
</ParamField>

## Query Parameters

<ParamField query="expand" type="array">
  Expand related objects. Options: "orders", "packages.items", "events", "documents"
</ParamField>

### Response

<ResponseField name="id" type="string">
  Unique shipment identifier
</ResponseField>

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

<ResponseField name="status" type="string">
  Current shipment status
</ResponseField>

<ResponseField name="tracking_number" type="string">
  Master tracking number
</ResponseField>

<ResponseField name="tracking_url" type="string">
  Tracking URL for customer
</ResponseField>

<ResponseField name="carrier" type="string">
  Shipping carrier
</ResponseField>

<ResponseField name="service_type" type="string">
  Service level
</ResponseField>

<ResponseField name="ship_date" type="string">
  Actual or scheduled ship date
</ResponseField>

<ResponseField name="delivery_date" type="string">
  Actual or estimated delivery date
</ResponseField>

<ResponseField name="packages" type="array">
  Array of packages in shipment
</ResponseField>

<ResponseField name="events" type="array">
  Tracking events (when expanded)
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://api.stateset.com/v1/shipments/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30?expand=events' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript Node.js theme={null}
  const shipment = await stateset.shipments.retrieve(
    'ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    { expand: ['events'] }
  );
  ```

  ```python Python theme={null}
  shipment = stateset.shipments.retrieve(
    'ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30',
    expand=['events']
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "shipment",
    "status": "in_transit",
    "created_at": "2024-01-19T14:30:00Z",
    "updated_at": "2024-01-20T10:15: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",
    "label_url": "https://labels.stateset.com/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30.pdf",
    "rate": {
      "amount": 1250,
      "currency": "USD",
      "carrier_account": "ups_12345"
    },
    "packages": [
      {
        "id": "pkg_abc123",
        "tracking_number": "1Z999AA10123456784",
        "label_url": "https://labels.stateset.com/ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30.pdf",
        "weight": {
          "value": 5.5,
          "unit": "lb"
        },
        "dimensions": {
          "length": 12,
          "width": 10,
          "height": 8,
          "unit": "in"
        },
        "value": 15000,
        "reference_number": "PKG-2024-001"
      }
    ],
    "from_address": {
      "name": "Main Distribution Center",
      "company": "Stateset",
      "line1": "456 Warehouse Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90001",
      "country": "US",
      "phone": "+1-555-987-6543"
    },
    "to_address": {
      "name": "John Doe",
      "company": "Acme Corp",
      "line1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90001",
      "country": "US",
      "phone": "+1-555-123-4567",
      "email": "john.doe@example.com"
    },
    "order_ids": ["order_123456", "order_123457"],
    "warehouse_id": "wh_001",
    "insurance": {
      "enabled": true,
      "amount": 15000,
      "currency": "USD",
      "provider": "ups",
      "confirmation_number": "INS123456"
    },
    "signature_required": true,
    "saturday_delivery": false,
    "events": [
      {
        "id": "evt_123",
        "created_at": "2024-01-20T08:05:00Z",
        "status": "label_created",
        "description": "Shipping label created",
        "location": {
          "city": "Los Angeles",
          "state": "CA",
          "country": "US"
        }
      },
      {
        "id": "evt_124",
        "created_at": "2024-01-20T09:30:00Z",
        "status": "picked_up",
        "description": "Package picked up by carrier",
        "location": {
          "city": "Los Angeles",
          "state": "CA",
          "country": "US"
        }
      },
      {
        "id": "evt_125",
        "created_at": "2024-01-20T10:15:00Z",
        "status": "in_transit",
        "description": "Package in transit",
        "location": {
          "city": "Los Angeles",
          "state": "CA",
          "country": "US",
          "facility": "Los Angeles Distribution Center"
        }
      }
    ],
    "metadata": {
      "internal_reference": "SHIP-2024-001",
      "priority": "standard"
    }
  }
  ```

  ```json Error Response (404 Not Found) theme={null}
  {
    "error": {
      "code": "RESOURCE_NOT_FOUND",
      "message": "Shipment not found",
      "details": {
        "resource": "shipment",
        "id": "shp_abc123"
      },
      "request_id": "req_abc123def456"
    }
  }
  ```

  ```json Error Response (401 Unauthorized) theme={null}
  {
    "error": {
      "code": "INVALID_API_KEY",
      "message": "The API key provided is invalid or has been revoked",
      "request_id": "req_abc123def456"
    }
  }
  ```
</ResponseExample>