Using Custom Packages

Once you have defined your custom packages, you can then use either the package_id or the package_code in the shipments object when creating your shipment or purchasing a label.

`package_id` vs `package_code`

When creating or updating shipments, you can provide either package_code or package_id. If both are included, package_code will take precedence. When getting rates or labels, only package_code is supported.

Sample Request & Response

In this example, we replace the dimensions object with the package_code property in the packages object.

POST /v2/shipments

POST /v2/shipments HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
 "shipments": [
   {
     "service_code": "usps_priority_mail",
     "shipment_status": "pending",
     "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"
     },
     "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"
         }
       }
     ]
   }
 ]
}

Response

In the response, you'll see the package_code property in the packages object (in addition to all its included properties), which indicates that it worked!

{
 "has_errors": false,
 "shipments": [
   {
     "errors": null,
     "address_validation": {
       "status": "verified",
       "original_address": {
         "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"
       },
       "matched_address": {
         "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"
       },
       "messages": []
     },
     "shipment_id": "se-41838065",
     "carrier_id": "se-123890",
     "service_code": "usps_priority_mail",
     "external_shipment_id": null,
     "ship_date": "2024-07-25T05:00:00.000Z",
     "created_at": "2024-07-25T15:24:46.657Z",
     "modified_at": "2024-07-25T15:24:46.657Z",
     "shipment_status": "pending",
     "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"
     },
     "warehouse_id": null,
     "return_to": {
       "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"
     },
     "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
         }
       }
     ]
   }
 ]
}