# Create Shipments

Create one or more shipments to prepare packages for label generation and tracking. Shipments contain all the information needed to ship packages including origin, destination, carrier preferences, and package details.

Coming from v1 or the ShipStation UI?
In v2, what you might know as **"orders"** are called **"shipments"**. This guide shows you how to create shipments (orders) using the v2 API.

**Key identifiers to understand:**

- **`external_shipment_id`** - Your system's unique identifier (maps to v1 `orderKey`)
- **`shipment_number`** - User-friendly display number (maps to v1 `orderNumber`)
- **`external_order_id`** - ShipStation UI order ID (optional, now settable)


**Important behaviors:**

- If you don't provide `external_shipment_id`, it will be auto-generated as `se-{shipment_id}`
- If you provide `external_shipment_id` but not `shipment_number`, the `shipment_number` will duplicate the `external_shipment_id` value
- Both `external_shipment_id` and `shipment_number` must be unique per account


For complete details, see:

- [External Identifiers Guide](/orders/external-identifiers)
- [Shipment Numbers & Uniqueness](/orders/shipment-numbers)
- [Understanding Orders & Shipments](/orders/understanding-orders-shipments)


## Create Shipments

Use the POST method with `/v2/shipments` to create one or more shipments. This endpoint accepts an array of shipments, allowing you to create multiple shipments in a single request.

### Request Body Properties

The request body contains a `shipments` array. Each shipment object supports the following properties:

| Property | Type | Required | Description |
|  --- | --- | --- | --- |
| `ship_to` | *object* | **Required** | Recipient shipping address |
| `ship_from` | *object* | **Required** | Origin shipping address |
| `packages` | *array* | **Required** | Package dimensions and weight (minimum 1 package) |
| `external_shipment_id` | *string* | Optional | Your internal shipment identifier (max 50 characters) |
| `carrier_id` | *string* | Optional | Carrier account to use for shipping |
| `service_code` | *string* | Optional | Specific carrier service (e.g., `fedex_ground`, `usps_priority_mail`) |
| `items` | *array* | Optional | Shipment line items with product details |
| `shipment_status` | *string* | Optional | Initial status: `pending`, `processing`, `label_purchased`, `cancelled` |
| `advanced_options` | *object* | Optional | Advanced shipping options (signature, Saturday delivery, etc.) |
| `customs` | *object* | Optional | International shipment customs information. Many countries have specific requirements for customs descriptions, tax IDs, and documentation. See [Country-Specific Shipping Requirements](/apis/docs/shipping/country-requirements) for details. |
| `insurance_provider` | *string* | Optional | Insurance provider: `none`, `shipsurance`, `parcelguard`, `xcover`, `carrier` |


### Example Request & Response

**POST /v2/shipments**

## Use Cases

**Bulk Import from Order System**
Import multiple orders from your e-commerce platform or order management system as shipments ready for rate shopping and label creation.

**Pre-Create for Rate Shopping**
Create shipments before purchasing labels to compare carrier rates and delivery times across multiple services.

**Batch Processing Workflows**
Prepare shipments in advance and process them in scheduled batches for efficient warehouse operations.

## Validation Rules

### Required Fields

- `ship_to` address (recipient)
- `ship_from` address (origin)
- `packages` array with at least one package


### Address Format

Addresses must include:

- `address_line_1`
- `city_locality`
- `postal_code`
- `country_code` (ISO 3166-1 alpha-2)


### Package Requirements

Each package requires:

- `weight` with `value` and `unit`
- Dimensions are optional but recommended for accurate rates


## Common Scenarios

**Create with specific carrier:**


```json
{
  "shipments": [{
    "carrier_id": "se-123456",
    "service_code": "usps_priority_mail",
    "ship_to": { ... },
    "ship_from": { ... },
    "packages": [{ ... }]
  }]
}
```

**Create without carrier (for rate shopping):**


```json
{
  "shipments": [{
    "ship_to": { ... },
    "ship_from": { ... },
    "packages": [{ ... }]
  }]
}
```

## Error Handling

Common errors when creating shipments:

**400 Bad Request**

- Missing required fields (ship_to, ship_from, packages)
- Invalid address format
- Invalid package weight or dimensions
- Invalid carrier_id or service_code


**500 Server Error**

- Temporary service issue - retry the request


## Related Resources

- [Update Shipments](/shipments/update) - Modify shipment details
- [List Shipments](/list-shipments) - Retrieve shipments
- [Create Labels](/create-labels) - Purchase labels for shipments