Site Logo

Size and Weight

Indicating the size and weight of your packages is key to getting accurate rates and ensuring your shipment is within the service guidelines set by your selected carrier. The more accurate your information is, the better the rate quote you will receive from the carriers.

If the size and weight details are incorrect, many carriers will charge you a post-shipment adjustment fee to make up the difference for the actual cost of the shipment. This may also result in your package being held by the carrier until the extra delivery cost is paid by you or the recipient. Additionally, if the size or weight you enter exceed the min or max limits for the selected service, you should receive an error from the carrier. This will help you know if you need to change to a different service or carrier for that parcel (and avoid potentiall costly adjustments from the carrier if you hand over a package that doesn't meet their service guidelines.)

Requirements

Add the weight and dimensions objects to the packages object when creating a shipment, creating a label, or getting a rate.

The weight object for a shipment's packages object is required and requires two properties:

PropertyTypeDescription
unitenumerated stringrequired
ounce, pound, gram, kilogram
valuedecimalrequired
The weight of the package in the unit specified.

The dimensions object for a shipment's packages object is optional (but recommended). When using this object, it requires four properties:

PropertyTypeDescription
unit enumerated stringrequired
inch, centimeter
lengthdecimalrequired
The package length in the unit specified.
widthdecimalrequired
The package width in the unit specified.
heightdecimalrequired
The package height in the unit specified.

Create Label Example Request

This example shows how to create a label for a package with a weight of 9.6 ounces, and dimensions of 12.0 x 7.1 x 6.0 inches.

POST /v1/labels/

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
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"packages": [
{
"weight": {
"value": 9.6,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 12.0,
"width": 7.1,
"height": 6.0
}
}
],
"service_code": "usps_priority_mail",
"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"
}
}
}

Both the package weight and dimension properties will be returned in the packages object in the response.

TIP:

Multi-Package Shipments

You'll notice that the packages object is an array of objects. This means for services that support multi-package shipping, you'll add multiple objects containing the relevant package details for each package that is part of a multi-package shipment.