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.
Use the PUT method with /v2/shipments/{shipment_id} to update an existing shipment's information.
| Parameter | Type | Description |
|---|---|---|
shipment_id | string | The unique identifier of the shipment to update |
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 |
The following fields cannot be updated:
shipment_id- System-assigned identifiercreated_at- Creation timestampmodified_at- Last modification timestamp (updated automatically)shipment_status- Status (use cancel endpoint to change to cancelled)tags- Use the tag endpoints to manage tagstotal_weight- Calculated from packages
On success, returns the updated shipment object with all current values.
PUT /v2/shipments/{shipment_id}
- Productionhttps://api.shipstation.com/v2/shipments/{shipment_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
https://api.shipstation.com/v2/shipments/se-28529731 \
-H 'Content-Type: application/json' \
-H 'api-key: YOUR_API_KEY_HERE' \
-d '{
"carrier_id": "se-1234567",
"service_code": "se_1234567",
"requested_shipment_service": "usps_priority_mail",
"shipping_rule_id": "se-1234",
"external_order_id": "1232434",
"hold_until_date": "2025-01-15T00:00:00.000Z",
"ship_by_date": "2025-01-15T00:00:00.000Z",
"retail_rate": {
"currency": "string",
"amount": 12
},
"store_id": "se-12345",
"items": [],
"notes_from_buyer": "Please handle with care",
"notes_for_gift": "Happy Birthday!",
"is_gift": true,
"assigned_user": "user@example.com",
"amount_paid": {
"currency": "string",
"amount": 12
},
"shipping_paid": {
"currency": "string",
"amount": 12
},
"tax_paid": {
"currency": "string",
"amount": 12
},
"zone": 1,
"display_scheme": "label",
"tax_identifiers": [
{
"taxable_entity_type": "shipper",
"identifier_type": "vat",
"issuing_authority": "US",
"value": "value"
}
],
"external_shipment_id": "1234556",
"shipment_number": "10001",
"ship_date": "2018-09-23T00:00:00Z",
"ship_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "yes",
"instructions": "any instruction",
"geolocation": [
{
"type": "what3words",
"value": "cats.with.thumbs"
}
]
},
"ship_from": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "yes",
"instructions": "any instructions"
},
"warehouse_id": null,
"return_to": {
"name": "John Doe",
"phone": "+1 204-253-9411 ext. 123",
"email": "example@example.com",
"company_name": "The Home Depot",
"address_line1": "1999 Bishop Grandin Blvd.",
"address_line2": "Unit 408",
"address_line3": "Building #7",
"city_locality": "Winnipeg",
"state_province": "Manitoba",
"postal_code": "78756-3717",
"country_code": "CA",
"address_residential_indicator": "yes",
"instructions": "any instructions"
},
"is_return": true,
"confirmation": "none",
"customs": null,
"advanced_options": {
"bill_to_account": "123456789",
"bill_to_country_code": "US",
"bill_to_party": "third_party",
"bill_to_postal_code": "28005",
"contains_alcohol": true,
"delivered_duty_paid": true,
"dry_ice": true,
"dry_ice_weight": {
"value": 23,
"unit": "pound"
},
"non_machinable": true,
"saturday_delivery": true,
"fedex_freight": {
"shipper_load_and_count": "shipper_load_and_count",
"booking_confirmation": "today"
},
"use_ups_ground_freight_pricing": true,
"freight_class": "77.5",
"custom_field1": "custom field 1",
"custom_field2": "custom field 2",
"custom_field3": "custom field 3",
"origin_type": null,
"additional_handling": true,
"shipper_release": true,
"collect_on_delivery": {
"payment_type": "any",
"payment_amount": {
"currency": "USD",
"amount": 12
}
},
"third_party_consignee": true,
"dangerous_goods": true,
"dangerous_goods_contact": {
"name": "Michael Robinson",
"phone": "123456578789"
},
"windsor_framework_details": {
"movement_indicator": "b2b",
"not_at_risk": true
},
"ancillary_endorsements_option": "forward",
"return_pickup_attempts": 3,
"own_document_upload": false,
"limited_quantity": false,
"event_notification": false,
"fragile": false,
"delivery_as_addressed": false,
"return_after_first_attempt": false,
"regulated_content_type": null
},
"insurance_provider": "none",
"tags": [],
"order_source_code": "amazon_ca",
"packages": [
{
"package_id": "se-123456",
"package_code": "thick_envelope",
"package_name": "Flat Rate Envelope",
"weight": {
"value": 23,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 2,
"width": 2,
"height": 1
},
"insured_value": [
{
"currency": "usd",
"amount": 0
}
],
"label_messages": {
"reference1": "Reference",
"reference2": "Reference 2",
"reference3": "Reference 3"
},
"external_package_id": "se-1234545",
"content_description": "Hand knitted wool socks",
"products": []
}
],
"comparison_rate_type": "retail",
"validate_address": "no_validation"
}'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.
Set validate_address to control address verification:
no_validation(default) - No validation performedvalidate_only- Validates without modifyingvalidate_and_clean- Validates and corrects addresses
If updating packages, each package requires:
- Valid
weightwithvalueandunit - Positive numeric values for dimensions
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
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.
- Create Shipments - Create new shipments
- List Shipments - Retrieve shipment information
- Cancel Shipments - Cancel shipments
- Create Labels - Purchase shipping labels