Size & Weight

Learn how to add details to your request that tell the carrier the size and weight of your package.

Accuracy is Key

You should strive to be as accurate as possible when shipping. The better the rate quote you will receive from the carriers.

Additionally, if the shipping information is incorrect, most carriers will follow up with a charge to make up the difference. This may result in your package being held until the extra delivery cost is paid by you or the recipient.

The Basics

Weight

Weight inside of a shipment's package is required.

Property
Description

unit

enumerated string, required

ounce, pound, gram, kilogram

value

decimal, required

Weight in the unit specified.

Dimensions

You can optionally specify the dimensions of each package in the shipment.

Property
Description

unit

enumerated string, required

inch, centimeter

length

decimal, required

Length in the unit specified.

width

decimal, required

Width in the unit specified.

height

decimal, required

Height in the unit specified.

Simply add the objects directly into the shipment object. This is the same format to use when getting shipping rates as well.

/v1/labels

Mickey is going to send us a stuffed version of himself, we know a couple new things. The shipping weight is 9.6 ounces, and the box dimensions are 12.0 x 7.1 x 6.0 inches.

curl $apiUrl$/v1/labels -XPOST \
  -H "Content-type: application/json" \
  -H $apiAuth$ \
  -d '
{
  "shipment": {
    "service_code": "usps_priority_mail",
    "ship_to": {
      "name": "Mickey and Minnie Mouse",
      "company_name": "The Walt Disney Company",
      "address_line1": "500 South Buena Vista Street",
      "city_locality": "Burbank",
      "state_province": "CA",
      "postal_code": "91521",
      "country_code": "US",
      "phone": "+1 (714) 781-4565"
    },
    "ship_from": {
      "name": "Dade Murphy",
      "phone": "512-485-4282",
      "company_name": "Zero Cool",
      "address_line1": "345 Chambers Street",
      "address_line2": "Suite 100",
      "city_locality": "New York City",
      "state_province": "NY",
      "postal_code": "10282",
      "country_code": "US"
    },
    "packages": [
      {
        "weight": {
          "value": 9.6,
          "unit": "ounce"
        },
        "dimensions": {
          "unit": "inch",
          "length": 12.0,
          "width": 7.1,
          "height": 6.0
        }
      }
    ]
  }
}'

We added the weight and dimensions object into shipment.packages[0]

"weight": {
  "value": 9.6,
  "unit": "ounce"
},
"dimensions": {
  "length": 12.0,
  "width": 7.1, 
  "height": 6.0, 
  "unit": "inch"
}
{
  "label_id": "se-test-202923521",
  "status": "processing",
  "shipment_id": "se-202923521",
  "ship_date": "$shipDate$",
  "created_at": "$date$",
  "shipment_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "insurance_cost": {
    "currency": "usd",
    "amount": 0.0
  },
  "tracking_number": "9999999999999",
  "is_return_label": false,
  "is_international": false,
  "batch_id": "",
  "carrier_id": "$stampsId$",
  "service_code": "usps_priority_mail",
  "package_code": "package",
  "voided": false,
  "voided_at": null,
  "label_format": "pdf",
  "label_layout": "4x6",
  "trackable": true,
  "carrier_code": "stamps_com",
  "tracking_status": "unknown",
  "label_download": {
    "pdf": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf",
    "png": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.png",
    "zpl": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.zpl",
    "href": "https://api.shipengine.com/v1/downloads/6/Q2OLdnGaqk-UzkN6pFH0lg/testlabel-202923521.pdf"
  },
  "form_download": null,
  "insurance_claim": null
}

Step 2: Ship It!

You can now print your label and ship it! Your label be found by navigating to label_download.href.


Size & Weight


Learn how to add details to your request that tell the carrier the size and weight of your package.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.