# Update Shipments

Update existing shipment information including addresses, package details, carrier service, and shipping options. Use this endpoint to correct or modify shipment details before purchasing a label.

## Update a Shipment

Use the PUT method with `/v2/shipments/{shipment_id}` to update an existing shipment's information.

### Path Parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `shipment_id` | *string* | The unique identifier of the shipment to update |


### Request Body Properties

All fields are optional - provide only the fields you want to update.

| Property | Type | Description |
|  --- | --- | --- |
| `ship_to` | *object* | Recipient shipping address |
| `ship_from` | *object* | Origin shipping address |
| `packages` | *array* | Package dimensions and weight |
| `carrier_id` | *string* | Carrier account to use |
| `service_code` | *string* | Carrier service code |
| `external_shipment_id` | *string* | Your internal identifier (max 50 chars) |
| `items` | *array* | Shipment line items |
| `advanced_options` | *object* | Advanced shipping options |
| `customs` | *object* | International customs information |
| `insurance_provider` | *string* | Insurance provider selection |
| `validate_address` | *string* | Address validation: `no_validation`, `validate_only`, `validate_and_clean` |


### Read-Only Fields

The following fields **cannot** be updated:

- `shipment_id` - System-assigned identifier
- `created_at` - Creation timestamp
- `modified_at` - Last modification timestamp (updated automatically)
- `shipment_status` - Status (use cancel endpoint to change to cancelled)
- `tags` - Use the tag endpoints to manage tags
- `total_weight` - Calculated from packages


### Response

On success, returns the updated shipment object with all current values.

### Example Request & Response

**PUT /v2/shipments/{shipment_id}**

## Common Update Scenarios

**Correct address before label purchase:**
Update the recipient address if you notice an error before creating a shipping label.

**Change carrier or service:**
Switch to a different carrier or service level after comparing rates.

**Update package dimensions:**
Adjust weight or dimensions after measuring packages more accurately.

**Add customs information:**
Add international shipping details for cross-border shipments.

## Validation Rules

### Address Validation

Set `validate_address` to control address verification:

- `no_validation` (default) - No validation performed
- `validate_only` - Validates without modifying
- `validate_and_clean` - Validates and corrects addresses


### Package Requirements

If updating packages, each package requires:

- Valid `weight` with `value` and `unit`
- Positive numeric values for dimensions


## Error Handling

Common errors when updating shipments:

**400 Bad Request**

- Invalid field format or value
- Invalid address format
- Invalid carrier_id or service_code
- Attempting to update read-only fields


**404 Not Found**

- Shipment ID not found
- Shipment may have been deleted


**500 Server Error**

- Temporary service issue - retry the request


## Best Practices

**Update before label purchase:** Once a label is purchased, some fields may become locked. Update shipments while in `pending` or `processing` status.

**Partial updates:** Only send fields you want to change - unchanged fields will retain their current values.

**Address validation:** Use `validate_and_clean` to catch address errors before purchasing labels.

## Related Resources

- [Create Shipments](/shipments/create) - Create new shipments
- [List Shipments](/list-shipments) - Retrieve shipment information
- [Cancel Shipments](/cancel-shipments) - Cancel shipments
- [Create Labels](/create-labels) - Purchase shipping labels