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