Using Custom Packages

Warning

Shipment Packages Accept Package Codes

Shipments, labels, and rates all take the package_code and do not take the package_id. The package_id is only for package management.

Example

POST /v1/shipments

curl -iX POST https://api.shipengine.com/v1/shipments \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "shipment_status": "pending",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "+1 (714) 781-4565",
        "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",
        "address_residential_indicator": "no"
      },
      "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",
        "address_residential_indicator": "no"
      },
      "confirmation": "none",
      "advanced_options": {},
      "insurance_provider": "none",
      "tags": [],
      "total_weight": {
        "value": 10.0,
        "unit": "ounce"
      },
      "packages": [
        {
          "package_code": "custom_laptop_box",
          "weight": {
            "value": 10.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}'

In the request we simply added to the packages collection:

"package_code": "custom_laptop_box"
{
  "has_errors": false,
  "shipments": [
    {
      "errors": null,
      "address_validation": {
        "status": "verified",
        "original_address": {
          "name": "Mickey and Minnie Mouse",
          "phone": "+1 (714) 781-4565",
          "company_name": "The Walt Disney Company",
          "address_line1": "500 South Buena Vista Street",
          "address_line2": null,
          "address_line3": null,
          "city_locality": "Burbank",
          "state_province": "CA",
          "postal_code": "91521",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "matched_address": {
          "name": "MICKEY AND MINNIE MOUSE",
          "phone": "+1 (714) 781-4565",
          "company_name": "THE WALT DISNEY COMPANY",
          "address_line1": "500 S BUENA VISTA ST",
          "address_line2": "",
          "address_line3": null,
          "city_locality": "BURBANK",
          "state_province": "CA",
          "postal_code": "91521-0007",
          "country_code": "US",
          "address_residential_indicator": "no"
        },
        "messages": []
      },
      "shipment_id": "se-41838065",
      "carrier_id": "se-123890",
      "service_code": "usps_priority_mail",
      "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": "MICKEY AND MINNIE MOUSE",
        "phone": "+1 (714) 781-4565",
        "company_name": "THE WALT DISNEY COMPANY",
        "address_line1": "500 S BUENA VISTA ST",
        "address_line2": "",
        "address_line3": null,
        "city_locality": "BURBANK",
        "state_province": "CA",
        "postal_code": "91521-0007",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "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",
        "address_residential_indicator": "unknown"
      },
      "warehouse_id": null,
      "return_to": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool 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": "unknown"
      },
      "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": [],
      "total_weight": {
        "value": 10.0,
        "unit": "ounce"
      },
      "packages": [
        {
          "package_code": "custom_laptop_box",
          "weight": {
            "value": 10.0,
            "unit": "ounce"
          },
          "dimensions": {
            "unit": "inch",
            "length": 15.00,
            "width": 20.00,
            "height": 5.00
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          }
        }
      ]
    }
  ]
}

In the response we see, it worked!

"package_code": "custom_laptop_box",
"dimensions": {
  "unit": "inch",
  "length": 15.00,
  "width": 20.00,
  "height": 5.00
}