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 exceeds 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 potential 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:

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

NOTE:

Shipment Dimensions and Weight Recommended!

While many carriers may allow you to create a label without including package dimensions, we recommend always adding package dimension values to your shipment (with the notable exception of flat rate boxes). This will ensure more accurate rate estimates, especially for carriers that rely on dimensional weight (also called DIM weight or volumetric weight).

The carrier_weight object in the response represents the weight assessed by the carrier based on the weight and dimensions provided when you create a shipment, generate a label, or obtain a rate. This feature is currently supported in the FedEx, Canpar, and Loomis Express integrations.

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/

HTTPcURLC#JavaScriptNodeJSPHPPythonRubyJavaGoSwiftObjective-CPowerShell

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.