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

# Create a Shipment

> Creates a new shipment with addresses and items

## Request Body

<ParamField body="shipment_date" type="string" required>
  Shipment date in ISO 8601 format
</ParamField>

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

<ParamField body="complete_at_start" type="string" required>
  Pickup window start time in ISO 8601 format
</ParamField>

<ParamField body="complete_at_end" type="string" required>
  Pickup window end time in ISO 8601 format
</ParamField>

<ParamField body="carrier_service_level_id" type="string" required>
  Carrier service level UUID
</ParamField>

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

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

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

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

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

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

    <ParamField body="country" type="string" required>
      Country code
    </ParamField>

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

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

    <ParamField body="latitude" type="number">
      Latitude
    </ParamField>

    <ParamField body="longitude" type="number">
      Longitude
    </ParamField>
  </Expandable>
</ParamField>

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

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

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

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

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

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

    <ParamField body="country" type="string" required>
      Country code
    </ParamField>

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

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

    <ParamField body="latitude" type="number">
      Latitude
    </ParamField>

    <ParamField body="longitude" type="number">
      Longitude
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="receiver_is_residential" type="boolean" default={false}>
  Is receiver address residential
</ParamField>

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

<ParamField body="label_url" type="string">
  Shipping label URL
</ParamField>

<ParamField body="timezone" type="string" default="America/New_York">
  IANA timezone identifier
</ParamField>

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

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

  <Expandable title="item properties">
    <ParamField body="title" type="string" required>
      Item title/name (1-255 characters)
    </ParamField>

    <ParamField body="length" type="number" required>
      Length
    </ParamField>

    <ParamField body="width" type="number" required>
      Width
    </ParamField>

    <ParamField body="height" type="number" required>
      Height
    </ParamField>

    <ParamField body="distance_unit" type="string" required>
      Unit of distance (in, cm)
    </ParamField>

    <ParamField body="weight" type="number" required>
      Weight
    </ParamField>

    <ParamField body="mass_unit" type="string" required>
      Unit of mass (lb, kg)
    </ParamField>

    <ParamField body="value" type="number">
      Declared value
    </ParamField>

    <ParamField body="currency" type="string">
      Currency code (USD)
    </ParamField>

    <ParamField body="description" type="string">
      Item description (max 1000 characters)
    </ParamField>

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

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

<RequestExample>
  ```json theme={null}
  {
    "shipment_date": "2023-11-07T10:00:00Z",
    "shipment_type": "delivery",
    "complete_at_start": "2023-11-07T14:00:00Z",
    "complete_at_end": "2023-11-07T18:00:00Z",
    "carrier_service_level_id": "550e8400-e29b-41d4-a716-446655440000",
    "shipper": {
      "name": "John Doe",
      "street": "123 Main St",
      "city": "Brooklyn",
      "state": "NY",
      "zip": "11201",
      "country": "US",
      "phone": "+1-555-123-4567",
      "email": "john@example.com"
    },
    "receiver": {
      "name": "Jane Smith",
      "street": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90001",
      "country": "US",
      "phone": "+1-555-987-6543",
      "email": "jane@example.com"
    },
    "receiver_is_residential": true,
    "order_number": "ORD-12345",
    "label_url": "https://example.com/labels/123.pdf",
    "items": [
      {
        "title": "Laptop",
        "length": 10.0,
        "width": 8.0,
        "height": 6.0,
        "distance_unit": "in",
        "weight": 2.5,
        "mass_unit": "lb",
        "value": 99.99,
        "currency": "USD"
      }
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order_number": "ORD-12345",
    "shipment_type": "delivery",
    "shipment_date": "2023-11-07T10:00:00Z",
    "complete_at_start": "2023-11-07T14:00:00Z",
    "complete_at_end": "2023-11-07T18: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",
    "label_url": "https://example.com/labels/123.pdf",
    "inserted_at": "2023-11-07T10:00:00Z",
    "updated_at": "2023-11-07T10:00:00Z"
  }
  ```
</ResponseExample>