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}

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": "usps_first_class_mail",
    "requested_shipment_service": "usps_priority_mail",
    "external_order_id": "1232434",
    "hold_until_date": "2025-01-15T00:00:00.000Z",
    "ship_by_date": "2025-01-15T00:00:00.000Z",
    "deliver_by_date": "2025-01-20T00:00:00.000Z",
    "retail_rate": {
      "currency": "usd",
      "amount": 12
    },
    "store_id": "se-12345",
    "items": [],
    "notes_from_buyer": "Please handle with care",
    "notes_to_buyer": "Thank you for your order!",
    "notes_for_gift": "Happy Birthday!",
    "internal_notes": "Check packaging before shipping",
    "is_gift": true,
    "assigned_user": "user@example.com",
    "amount_paid": {
      "currency": "usd",
      "amount": 12
    },
    "shipping_paid": {
      "currency": "usd",
      "amount": 12
    },
    "tax_paid": {
      "currency": "usd",
      "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",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "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",
      "geolocation": [
        {
          "type": "what3words",
          "value": "cats.with.thumbs"
        }
      ]
    },
    "is_return": true,
    "confirmation": "none",
    "customs": {
      "terms_of_trade_code": "ddp",
      "contents": "gift",
      "non_delivery": "return_to_sender"
    },
    "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"
      },
      "movement_indicator": "b2b",
      "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,
      "netstamps_options": {
        "row": 1,
        "column": 1
      }
    },
    "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"
  }'

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.

Create Shipments - Create new shipments
List Shipments - Retrieve shipment information
Cancel Shipments - Cancel shipments
Create Labels - Purchase shipping labels