Update a Shipment

Occasionally you may need to update a shipment's details after you've created the shipment but before shippign it. For instance, the package's size and weight have changed since you created the original shipment, or you may realize you didn't add necessary customs declarations.

Requirements

The request URL must include the shipment_id (available from the create a shipment response, or you can get a shipment by key to find your shipment_id).
You'll need the ship_to and either the ship_from or warehouse_id properties.
You'll need any of the other properties you wish to update.

See Update Shipment By ID in our API reference for the full body schema.

Example Shipment Update Request & Response

In this example, we'll update the size and weight of a shipment. You can add the same parameters used in Size & Weight to update the shipment.

PUT /v1/shipments/:shipment_id

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
PUT /v1/shipments/se-202902255 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "validate_address": "no_validation",
  "carrier_id": "se-123890",
  "service_code": "usps_priority_mail",
  "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
  "ship_date": "2019-07-25T05:00:00.000Z",
  "created_at": "2019-07-25T15:24:46.657Z",
  "modified_at": "2019-07-25T15:24:46.657Z",
  "shipment_status": "pending",
  "ship_to": {
    "name": "Amanda Miller",
    "phone": "555-555-5555",
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US",
    "address_residential_indicator": "yes"
  },
  "ship_from": {
    "company_name": "Example Corp.",
    "name": "John Doe",
    "phone": "111-111-1111",
    "address_line1": "4009 Marathon Blvd",
    "address_line2": "Suite 300",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78756",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "return_to": {
    "phone": "222-222-2222",
    "company_name": "Example Corp. Returns",
    "address_line1": "345 Chambers Street",
    "address_line2": "Suite 100",
    "city_locality": "New York City",
    "state_province": "NY",
    "postal_code": "10282",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "confirmation": "none",
  "advanced_options": {
    "bill_to_account": null,
    "bill_to_country_code": null,
    "bill_to_party": null,
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "non_machinable": false,
    "saturday_delivery": false
  },
  "insurance_provider": "none",
  "tags": [],
  "packages": [
    {
      "weight": {
        "value": 9.6,
        "unit": "ounce"
      },
      "dimensions": {
        "unit": "inch",
        "length": 12.0,
        "width": 7.1,
        "height": 6.0
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.0
      }
    }
  ]
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
{
  "errors": [],
  "address_validation": null,
  "shipment_id": "se-5332095",
  "carrier_id": null,
  "service_code": null,
  "external_shipment_id": null,
  "ship_date": "2019-07-25T05:00:00.000Z",
  "created_at": "2019-07-25T15:24:46.657Z",
  "modified_at": "2019-07-25T15:24:46.657Z",
  "shipment_status": "pending",
  "ship_to": {
    "name": "Amanda Miller",
    "phone": "555-555-5555",
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US",
    "address_residential_indicator": "yes"
  },
  "ship_from": {
    "company_name": "Example Corp.",
    "name": "John Doe",
    "phone": "111-111-1111",
    "address_line1": "4009 Marathon Blvd",
    "address_line2": "Suite 300",
    "city_locality": "Austin",
    "state_province": "TX",
    "postal_code": "78756",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "warehouse_id": "se-7429",
  "return_to": {
    "phone": "222-222-2222",
    "company_name": "Example Corp. Returns",
    "address_line1": "345 Chambers Street",
    "address_line2": "Suite 100",
    "city_locality": "New York City",
    "state_province": "NY",
    "postal_code": "10282",
    "country_code": "US",
    "address_residential_indicator": "no"
  },
  "confirmation": "none",
  "customs": null,
  "external_order_id": null,
  "order_source_code": null,
  "advanced_options": {
    "bill_to_account": null,
    "bill_to_country_code": null,
    "bill_to_party": null,
    "bill_to_postal_code": null,
    "contains_alcohol": false,
    "delivered_duty_paid": false,
    "non_machinable": false,
    "saturday_delivery": false,
    "dry_ice": false,
    "dry_ice_weight": null,
    "freight_class": null,
    "custom_field1": null,
    "custom_field2": null,
    "custom_field3": null,
    "collect_on_delivery": null
  },
  "insurance_provider": "none",
  "tags": [],
  "packages": [
    {
      "package_code": "package",
      "weight": {
        "value": 0.0,
        "unit": "ounce"
      },
      "dimensions": {
        "unit": "inch",
        "length": 0.0,
        "width": 0.0,
        "height": 0.0
      },
      "insured_value": {
        "currency": "usd",
        "amount": 0.0
      },
      "label_messages": {
        "reference1": null,
        "reference2": null,
        "reference3": null
      },
      "external_package_id": null
    }
  ],
  "total_weight": {
    "value": 0.0,
    "unit": "ounce"
  },
  "items": []
}