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

# Create Shipment

> Create a shipment for outbound orders

<Note>
  This endpoint creates a new shipment for one or more orders. It handles carrier integration, label generation, and tracking initialization.
</Note>

## Authentication

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

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

## Request Body

<ParamField body="order_ids" type="array" required>
  Array of order IDs to include in this shipment
</ParamField>

<ParamField body="warehouse_id" type="string" required>
  Origin warehouse ID
</ParamField>

<ParamField body="carrier" type="string" required>
  Carrier for shipment (e.g., "ups", "fedex", "usps", "dhl")
</ParamField>

<ParamField body="service_type" type="string" required>
  Service level (e.g., "ground", "express", "overnight", "2day")
</ParamField>

<ParamField body="ship_date" type="string" required>
  Scheduled ship date (ISO 8601)
</ParamField>

<ParamField body="shipping_address" type="object" required>
  Destination address

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

    <ParamField body="company" type="string">
      Company name
    </ParamField>

    <ParamField body="line1" type="string" required>
      Street address line 1
    </ParamField>

    <ParamField body="line2" type="string">
      Street address line 2
    </ParamField>

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

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

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

    <ParamField body="country" type="string" required>
      ISO 3166-1 alpha-2 country code
    </ParamField>

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

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

<ParamField body="packages" type="array" required>
  Array of packages in the shipment

  <Expandable title="Package properties">
    <ParamField body="weight" type="object" required>
      Package weight

      <Expandable title="Weight properties">
        <ParamField body="value" type="number" required>
          Weight value
        </ParamField>

        <ParamField body="unit" type="string" required>
          Weight unit ("lb" or "kg")
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="dimensions" type="object" required>
      Package dimensions

      <Expandable title="Dimension properties">
        <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="unit" type="string" required>
          Dimension unit ("in" or "cm")
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="items" type="array">
      Items in this package
    </ParamField>

    <ParamField body="package_type" type="string">
      Package type (e.g., "box", "envelope", "tube")
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="insurance" type="object">
  Insurance options

  <Expandable title="Insurance properties">
    <ParamField body="enabled" type="boolean">
      Whether to insure the shipment
    </ParamField>

    <ParamField body="amount" type="integer">
      Insurance value in cents
    </ParamField>

    <ParamField body="currency" type="string">
      ISO 4217 currency code
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="signature_required" type="boolean">
  Whether signature is required on delivery
</ParamField>

<ParamField body="saturday_delivery" type="boolean">
  Whether to enable Saturday delivery
</ParamField>

<ParamField body="customs_info" type="object">
  Customs information for international shipments

  <Expandable title="Customs properties">
    <ParamField body="contents_type" type="string">
      Type of contents (e.g., "merchandise", "gift", "sample")
    </ParamField>

    <ParamField body="customs_items" type="array">
      Array of customs line items
    </ParamField>

    <ParamField body="eel_pfc" type="string">
      Electronic Export Information or Proof of Filing Citation
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="reference_numbers" type="object">
  Reference numbers for tracking

  <Expandable title="Reference properties">
    <ParamField body="po_number" type="string">
      Purchase order number
    </ParamField>

    <ParamField body="invoice_number" type="string">
      Invoice number
    </ParamField>

    <ParamField body="reference_1" type="string">
      Custom reference 1
    </ParamField>

    <ParamField body="reference_2" type="string">
      Custom reference 2
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="label_format" type="string">
  Label format preference ("pdf", "zpl", "png")
</ParamField>

<ParamField body="metadata" type="object">
  Additional custom fields
</ParamField>

### Response

Returns the created shipment with tracking information and label URLs.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://api.stateset.com/v1/shipments' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data-raw '{
      "order_ids": ["order_123456", "order_123457"],
      "warehouse_id": "wh_001",
      "carrier": "ups",
      "service_type": "ground",
      "ship_date": "2024-01-20T08:00:00Z",
      "shipping_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"
      },
      "packages": [
          {
              "weight": {
                  "value": 5.5,
                  "unit": "lb"
              },
              "dimensions": {
                  "length": 12,
                  "width": 10,
                  "height": 8,
                  "unit": "in"
              },
              "package_type": "box"
          }
      ],
      "insurance": {
          "enabled": true,
          "amount": 15000,
          "currency": "USD"
      },
      "signature_required": true
  }'
  ```

  ```javascript Node.js theme={null}
  const shipment = await stateset.shipments.create({
    order_ids: ["order_123456", "order_123457"],
    warehouse_id: "wh_001",
    carrier: "ups",
    service_type: "ground",
    ship_date: "2024-01-20T08:00:00Z",
    shipping_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"
    },
    packages: [
      {
        weight: { value: 5.5, unit: "lb" },
        dimensions: { length: 12, width: 10, height: 8, unit: "in" },
        package_type: "box"
      }
    ],
    signature_required: true
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "ship_0901f083-aa1c-43c5-af5c-0a9d2fc64e30",
    "object": "shipment",
    "status": "label_created",
    "created_at": "2024-01-19T14:30:00Z",
    "ship_date": "2024-01-20T08: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",
      "estimated_delivery_date": "2024-01-23T18:00:00Z"
    },
    "packages": [
      {
        "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"
        }
      }
    ],
    "from_address": {
      "name": "Main Distribution Center",
      "line1": "456 Warehouse Blvd",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90001",
      "country": "US"
    },
    "to_address": {
      "name": "John Doe",
      "company": "Acme Corp",
      "line1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "postal_code": "90001",
      "country": "US"
    },
    "order_ids": ["order_123456", "order_123457"],
    "insurance": {
      "enabled": true,
      "amount": 15000,
      "currency": "USD",
      "provider": "ups"
    }
  }
  ```
</ResponseExample>