Size and Weight

info

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.

Example

POST /v1/labels/

This example shows how to ship a package with a shipping weight of 9.6 ounces, and box dimensions of 12.0 x 7.1 x 6.0 inches.

curl -iX POST https://api.shipengine.com/v1/labels \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "shipment": {
    "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"
    },
    "packages": [
      {
        "weight": {
          "value": 9.6,
          "unit": "ounce"
        },
        "dimensions": {
          "unit": "inch",
          "length": 12.0,
          "width": 7.1,
          "height": 6.0
        }
      }
    ]
  }
}'
  • curl

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": "2019-07-25T05:00:00.000Z",
  "created_at": "2019-07-25T15:24:46.657Z",
  "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": "se-123890",
  "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.