# Multi-Package Shipping Multi-package shipping is when you create multiple labels for a set of packages that are part of a single shipment. When you use multi-package shipping, you can group packages together, get discounted rates, and retrieve a one-to-many "master" tracking number for all packages in the shipment. When submitting a request for multi-package labels, you'll add each package's details into the `packages` array in the shipment object. ## Requirements * You must have the weight, dimensions, and insurance properties (if applicable) for each package in the shipment. * You must use a carrier and service that supports multi-package shipping. * Not all carriers and services support multi-package shipping. To learn which services support multi-package check the `is_multi_package_supported` property when listing carriers or listing carrier services via the API reference. * Popular carriers that have multi-package services include FedEx, UPS, DHL Express, DHL Express Canada, DHL Express UK, FirstMile, and Purolator Canada. Package Types for Multi-Package Shipping All multi-package shipment labels created with ShipStation API will use the `package` package type. This is because carrier-specific packaging is not widely supported by carriers for multi-package shipping. Rate requests for multi-package shipments that include carrier-specific package types *may* return rates. However, any labels created from the quoted rates will update the package type to `package`. ## Example Request & Response This example includes weight, insurance, and dimension properties for two packages. When adding insurance for multi-package shipping, you can specify unique insurance values for each package. **POST /v2/labels** ```http POST /v2/labels HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "shipment": { "service_code": "fedex_express_saver", "ship_to": { "name": "Amanda Miller", "phone": "555-555-5555", "email": "recipient@example.com", "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", "email": "sender@example.com", "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" }, "insurance_provider": "carrier", "packages": [ { "weight": { "value": 10.0, "unit": "ounce" }, "insured_value": { "amount": 110.00, "currency": "USD" }, "dimensions": { "length": 10, "height": 10, "width": 10, "unit": "inch" } }, { "weight": { "value": 20.0, "unit": "ounce" }, "insured_value": { "amount": 200.00, "currency": "USD" }, "dimensions": { "length": 15, "height": 15, "width": 15, "unit": "inch" } } ] } } ``` **Response** In the response, we consolidate all of the labels for a multi-package shipment into a multi-page PDF or ZPL file in the `label_download` object. Currently, we don't support the PNG format for multi-package label downloads. However, each package will also have their own `label_download` object. ```json { "label_id": "se-120646641", "status": "completed", "shipment_id": "se-236897068", "ship_date": "2022-01-04T00:00:00Z", "created_at": "2022-01-04T19:13:22.3055032Z", "shipment_cost": { "currency": "usd", "amount": 205.69 }, "insurance_cost": { "currency": "usd", "amount": 6.3 }, "tracking_number": "794699375744", "is_return_label": false, "rma_number": null, "is_international": false, "batch_id": "", "carrier_id": "se-121495", "service_code": "fedex_express_saver", "package_code": "package", "voided": false, "voided_at": null, "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": null, "carrier_code": "fedex", "tracking_status": "in_transit", "label_download": { "pdf": "https://api.shipstation.com/v2/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.pdf", "zpl": "https://api.shipstation.com/v2/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.zpl", "href": "https://api.shipstation.com/v2/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.pdf" }, "form_download": null, "insurance_claim": null, "packages": [ { "package_id": 127246591, "package_code": "package", "weight": { "value": 10.00, "unit": "ounce" }, "dimensions": { "unit": "inch", "length": 10.00, "width": 10.00, "height": 10.00 }, "insured_value": { "currency": "usd", "amount": 110.00 }, "tracking_number": "794699375744", "label_download": { "pdf": "https://api.shipstation.com/v2/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.pdf", "png": "https://api.shipstation.com/v2/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.png", "zpl": "https://api.shipstation.com/v2/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.zpl" }, "label_messages": { "reference1": null, "reference2": null, "reference3": null }, "external_package_id": null, "sequence": 1 }, { "package_id": 127246592, "package_code": "package", "weight": { "value": 20.00, "unit": "ounce" }, "dimensions": { "unit": "inch", "length": 15.00, "width": 15.00, "height": 15.00 }, "insured_value": { "currency": "usd", "amount": 200.00 }, "tracking_number": "794699375788", "label_download": { "pdf": "https://api.shipstation.com/v2/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.pdf", "png": "https://api.shipstation.com/v2/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.png", "zpl": "https://api.shipstation.com/v2/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.zpl" }, "label_messages": { "reference1": null, "reference2": null, "reference3": null }, "external_package_id": null, "sequence": 2 } ], "charge_event": "carrier_default" } ``` ## Label Examples ### Master Tracking Label This is the master tracking label, the first label in the series. ![](/assets/master-label.70c7da3f6e21e274349bb26312cc6a5a3a0d500fb434d5173a9dca813662e1e1.c11a54a9.png) ### Second Label This is the second label in the series. It has its own "child" tracking number but also includes the master tracking number it's connected to. ![](/assets/second-label.f6c6ef81c7a76b1dbbfde2d840d99836b80974e996ffa44cae196c23597f975f.c11a54a9.png)