> ## 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 Batch of Shipments

> Creates multiple shipments as a batch with a single pickup

## Request Body

<ParamField body="shipments" type="array" required>
  List of shipments to create (1-100 shipments)

  <Expandable title="shipment properties">
    <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 (same structure as single shipment)
    </ParamField>

    <ParamField body="receiver" type="object" required>
      Receiver address information (same structure as single shipment)
    </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="timezone" type="string" default="America/New_York">
      IANA timezone identifier
    </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>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<RequestExample>
  ```json theme={null}
  {
    "shipments": [
      {
        "shipment_date": "2023-11-08T10:00:00Z",
        "shipment_type": "delivery",
        "complete_at_start": "2023-11-08T14:00:00-05:00",
        "complete_at_end": "2023-11-08T18:00:00-05:00",
        "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": "7185551234",
          "email": "john@example.com"
        },
        "receiver": {
          "name": "Jane Smith",
          "street": "456 Oak Ave",
          "city": "Brooklyn",
          "state": "NY",
          "zip": "11215",
          "country": "US",
          "phone": "7185559876",
          "email": "jane@example.com"
        },
        "receiver_is_residential": true,
        "order_number": "ORD-001",
        "timezone": "America/New_York",
        "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}
  {
    "pickup_id": "123e4567-e89b-12d3-a456-426614174000",
    "shipments": [
      {
        "id": "456e7890-e89b-12d3-a456-426614174001",
        "order_number": "ORD-001",
        "shipment_type": "delivery",
        "shipment_date": "2023-11-08T10:00:00Z",
        "complete_at_start": "2023-11-08T19:00:00Z",
        "complete_at_end": "2023-11-08T23:00:00Z",
        "carrier_id": "660e8400-e29b-41d4-a716-446655440000",
        "carrier_service_level_id": "550e8400-e29b-41d4-a716-446655440000",
        "pickup_id": "123e4567-e89b-12d3-a456-426614174000",
        "timezone": "America/New_York",
        "inserted_at": "2023-11-07T10:00:00Z",
        "updated_at": "2023-11-07T10:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>

<Note>
  All shipments in a batch share the same pickup. The pickup window times should be coordinated to ensure all shipments can be collected together.
</Note>

## Response Fields

<ResponseField name="pickup_id" type="string">
  Unique identifier for the shared pickup (UUID format)
</ResponseField>

<ResponseField name="shipments" type="array">
  List of created shipments with the same structure as individual shipment responses
</ResponseField>