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

# Update Shipment

> Updates a shipment including addresses and items. Only pending or scheduled shipments can be updated.

## Request Parameters

### Path Parameters

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

### Request Body

<ParamField body="order_number" type="string">
  Order reference number
</ParamField>

<ParamField body="shipment_date" type="string">
  Date and time for the shipment in ISO 8601 format
</ParamField>

<ParamField body="shipment_type" type="string">
  Type of shipment. Must be one of: `delivery`, `return`, `exchange`
</ParamField>

<ParamField body="complete_at_start" type="string">
  Start of pickup window in ISO 8601 format
</ParamField>

<ParamField body="complete_at_end" type="string">
  End of pickup window in ISO 8601 format
</ParamField>

<ParamField body="carrier_service_level_id" type="string">
  UUID of the carrier service level
</ParamField>

<ParamField body="shipper" type="object">
  Shipper address information

  <Expandable title="properties">
    <ParamField body="name" type="string">
      Shipper name
    </ParamField>

    <ParamField body="street" type="string">
      Street address
    </ParamField>

    <ParamField body="city" type="string">
      City
    </ParamField>

    <ParamField body="state" type="string">
      State/Province code
    </ParamField>

    <ParamField body="zip" type="string">
      ZIP/Postal code
    </ParamField>

    <ParamField body="country" type="string">
      Country code (default: US)
    </ParamField>

    <ParamField body="phone" type="string">
      Contact phone number
    </ParamField>

    <ParamField body="email" type="string">
      Contact email
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="receiver" type="object">
  Receiver address information

  <Expandable title="properties">
    <ParamField body="name" type="string">
      Receiver name
    </ParamField>

    <ParamField body="street" type="string">
      Street address
    </ParamField>

    <ParamField body="city" type="string">
      City
    </ParamField>

    <ParamField body="state" type="string">
      State/Province code
    </ParamField>

    <ParamField body="zip" type="string">
      ZIP/Postal code
    </ParamField>

    <ParamField body="country" type="string">
      Country code (default: US)
    </ParamField>

    <ParamField body="phone" type="string">
      Contact phone number
    </ParamField>

    <ParamField body="email" type="string">
      Contact email
    </ParamField>

    <ParamField body="receiver_is_residential" type="boolean">
      Is this a residential address? (default: false)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="update_reason" type="string">
  Reason for the update (for audit trail)
</ParamField>

<ParamField body="timezone" type="string">
  IANA timezone identifier (default: America/New\_York)
</ParamField>

<ParamField body="label_url" type="string">
  URL to the shipping label
</ParamField>

<ParamField body="metadata" type="object">
  Additional metadata for the shipment
</ParamField>

<ParamField body="items" type="array">
  List of items in the shipment

  <Expandable title="item properties">
    <ParamField body="value" type="number">
      Declared value of the item
    </ParamField>

    <ParamField body="weight" type="number">
      Weight of the item
    </ParamField>

    <ParamField body="length" type="number">
      Length of the item
    </ParamField>

    <ParamField body="width" type="number">
      Width of the item
    </ParamField>

    <ParamField body="height" type="number">
      Height of the item
    </ParamField>

    <ParamField body="distance_unit" type="string">
      Unit for dimensions (in, cm)
    </ParamField>

    <ParamField body="mass_unit" type="string">
      Unit for weight (lb, kg)
    </ParamField>

    <ParamField body="currency" type="string">
      Currency for the value (default: USD)
    </ParamField>

    <ParamField body="image_url" type="string">
      URL to item image
    </ParamField>

    <ParamField body="metadata" type="object">
      Additional item metadata
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "order_number": "UPDATED-ORD-12345",
    "complete_at_start": "2023-11-09T09:00:00-05:00",
    "complete_at_end": "2023-11-09T17:00:00-05:00",
    "receiver": {
      "name": "Jane Doe Updated",
      "street": "789 New Street",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001"
    },
    "update_reason": "Customer requested address change"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_number": "UPDATED-ORD-12345",
    "shipment_type": "delivery",
    "shipment_date": "2023-11-09T10:00:00Z",
    "complete_at_start": "2023-11-09T14:00:00Z",
    "complete_at_end": "2023-11-09T22:00:00Z",
    "carrier_id": "660e8400-e29b-41d4-a716-446655440000",
    "carrier_service_level_id": "550e8400-e29b-41d4-a716-446655440000",
    "pickup_id": "770e8400-e29b-41d4-a716-446655440000",
    "timezone": "America/New_York",
    "inserted_at": "2023-11-07T10:00:00Z",
    "updated_at": "2023-11-08T15:30:00Z"
  }
  ```
</ResponseExample>