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
}
}
]
}
]
}