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

## 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 |
| `insurance_provider` | *string* | Optional | Insurance provider: `none`, `shipsurance`, `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