{"templateId":"markdown","versions":[{"version":"shipstation-v2","label":"ShipStation V2 API","link":"/apis/shipstation-v2/docs/shipping/multi-package","default":true,"active":false,"folderId":"58c9a61d"},{"version":"shipengine","label":"ShipStation API (formerly ShipEngine)","link":"/apis/shipengine/docs/shipping/multi-package","default":false,"active":true,"folderId":"58c9a61d"},{"version":"shipstation-v1","label":"ShipStation V1 API","link":"/apis/shipstation-v1/docs/shipping/multi-package","default":false,"active":false,"folderId":"58c9a61d"}],"sharedDataIds":{"sidebar":"sidebar-apis/@shipengine/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Multi-Package Shipping","keywords":"shipping, labels, shipstation, documentation, api","siteUrl":"https://docs.shipstation.com","lang":"en-US","llmstxt":{"hide":false,"title":"ShipStation API LLM Docs","description":"Find links and references to all markdown documentation for use with LLMs","excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"multi-package-shipping","__idx":0},"children":["Multi-Package Shipping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When submitting a request for multi-package labels, you'll add each package's details into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["packages"]}," array in the shipment object."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"requirements","__idx":1},"children":["Requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You must have the weight, dimensions, and insurance properties (if applicable) for each package in the shipment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You must use a carrier and service that supports multi-package shipping.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Not all carriers and services support multi-package shipping. To learn which services support multi-package check the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_multi_package_supported"]}," property when ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/list-carriers"},"children":["listing carriers"]}," or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/apis/shipengine/docs/reference/list-carrier-services"},"children":["listing carrier services"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Popular carriers that have multi-package services include FedEx, UPS, DHL Express, DHL Express Canada, DHL Express UK, FirstMile, and Purolator Canada."]}]}]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["NOTE:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"package-types-for-multi-package-shipping","__idx":2},"children":["Package Types for Multi-Package Shipping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All multi-package shipment labels created with ShipStation API will use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package"]}," package type. This is because carrier-specific packaging is not widely supported by carriers for multi-package shipping."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rate requests for multi-package shipments that include carrier-specific package types ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["may"]}," return rates. However, any labels created from the quoted rates will update the package type to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["package"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-request--response","__idx":3},"children":["Example Request & Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST /v1/labels"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /v1/labels HTTP/1.1\nHost: api.shipengine.com\nAPI-Key: __YOUR_API_KEY_HERE__\nContent-Type: application/json\n\n{\n  \"shipment\": {\n    \"service_code\": \"fedex_express_saver\",\n    \"ship_to\": {\n      \"name\": \"Amanda Miller\",\n      \"phone\": \"555-555-5555\",\n      \"email\": \"recipient@example.com\",\n      \"address_line1\": \"525 S Winchester Blvd\",\n      \"city_locality\": \"San Jose\",\n      \"state_province\": \"CA\",\n      \"postal_code\": \"95128\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"yes\"\n    },\n    \"ship_from\": {\n      \"company_name\": \"Example Corp.\",\n      \"name\": \"John Doe\",\n      \"phone\": \"111-111-1111\",\n      \"email\": \"sender@example.com\",\n      \"address_line1\": \"4009 Marathon Blvd\",\n      \"address_line2\": \"Suite 300\",\n      \"city_locality\": \"Austin\",\n      \"state_province\": \"TX\",\n      \"postal_code\": \"78756\",\n      \"country_code\": \"US\",\n      \"address_residential_indicator\": \"no\"\n    },\n    \"insurance_provider\": \"carrier\",\n    \"packages\": [\n      {\n        \"weight\": {\n          \"value\": 10.0,\n          \"unit\": \"ounce\"\n        },\n        \"insured_value\": {\n          \"amount\": 110.00,\n          \"currency\": \"USD\"\n        },\n        \"dimensions\": {\n          \"length\": 10,\n          \"height\": 10,\n          \"width\": 10,\n          \"unit\": \"inch\"\n        }\n      },\n      {\n        \"weight\": {\n          \"value\": 20.0,\n          \"unit\": \"ounce\"\n        },\n        \"insured_value\": {\n          \"amount\": 200.00,\n          \"currency\": \"USD\"\n        },\n        \"dimensions\": {\n          \"length\": 15,\n          \"height\": 15,\n          \"width\": 15,\n          \"unit\": \"inch\"\n        }\n      }\n    ]\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the response, we consolidate all of the labels for a multi-package shipment into a multi-page PDF or ZPL file in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_download"]}," object. Currently, we don't support the PNG format for multi-package label downloads. However, each package will also have their own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label_download"]}," object."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"label_id\": \"se-120646641\",\n    \"status\": \"completed\",\n    \"shipment_id\": \"se-236897068\",\n    \"ship_date\": \"2022-01-04T00:00:00Z\",\n    \"created_at\": \"2022-01-04T19:13:22.3055032Z\",\n    \"shipment_cost\": {\n        \"currency\": \"usd\",\n        \"amount\": 205.69\n    },\n    \"insurance_cost\": {\n        \"currency\": \"usd\",\n        \"amount\": 6.3\n    },\n    \"tracking_number\": \"794699375744\",\n    \"is_return_label\": false,\n    \"rma_number\": null,\n    \"is_international\": false,\n    \"batch_id\": \"\",\n    \"carrier_id\": \"se-121495\",\n    \"service_code\": \"fedex_express_saver\",\n    \"package_code\": \"package\",\n    \"voided\": false,\n    \"voided_at\": null,\n    \"label_format\": \"pdf\",\n    \"display_scheme\": \"label\",\n    \"label_layout\": \"4x6\",\n    \"trackable\": true,\n    \"label_image_id\": null,\n    \"carrier_code\": \"fedex\",\n    \"tracking_status\": \"in_transit\",\n    \"label_download\": {\n        \"pdf\": \"https://api.shipengine.com/v1/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.pdf\",\n        \"zpl\": \"https://api.shipengine.com/v1/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.zpl\",\n        \"href\": \"https://api.shipengine.com/v1/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.pdf\"\n    },\n    \"form_download\": null,\n    \"insurance_claim\": null,\n    \"packages\": [\n        {\n            \"package_id\": 127246591,\n            \"package_code\": \"package\",\n            \"weight\": {\n                \"value\": 10.00,\n                \"unit\": \"ounce\"\n            },\n            \"dimensions\": {\n                \"unit\": \"inch\",\n                \"length\": 10.00,\n                \"width\": 10.00,\n                \"height\": 10.00\n            },\n            \"insured_value\": {\n                \"currency\": \"usd\",\n                \"amount\": 110.00\n            },\n            \"tracking_number\": \"794699375744\",\n            \"label_download\": {\n                \"pdf\": \"https://api.shipengine.com/v1/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.pdf\",\n                \"png\": \"https://api.shipengine.com/v1/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.png\",\n                \"zpl\": \"https://api.shipengine.com/v1/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.zpl\"\n            },\n            \"label_messages\": {\n                \"reference1\": null,\n                \"reference2\": null,\n                \"reference3\": null\n            },\n            \"external_package_id\": null,\n            \"sequence\": 1\n        },\n        {\n            \"package_id\": 127246592,\n            \"package_code\": \"package\",\n            \"weight\": {\n                \"value\": 20.00,\n                \"unit\": \"ounce\"\n            },\n            \"dimensions\": {\n                \"unit\": \"inch\",\n                \"length\": 15.00,\n                \"width\": 15.00,\n                \"height\": 15.00\n            },\n            \"insured_value\": {\n                \"currency\": \"usd\",\n                \"amount\": 200.00\n            },\n            \"tracking_number\": \"794699375788\",\n            \"label_download\": {\n                \"pdf\": \"https://api.shipengine.com/v1/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.pdf\",\n                \"png\": \"https://api.shipengine.com/v1/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.png\",\n                \"zpl\": \"https://api.shipengine.com/v1/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.zpl\"\n            },\n            \"label_messages\": {\n                \"reference1\": null,\n                \"reference2\": null,\n                \"reference3\": null\n            },\n            \"external_package_id\": null,\n            \"sequence\": 2\n        }\n    ],\n    \"charge_event\": \"carrier_default\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"label-examples","__idx":4},"children":["Label Examples"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"master-tracking-label","__idx":5},"children":["Master Tracking Label"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the master tracking label, the first label in the series."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/master-label.96c946cc7bc7ea962202cf89f5898914a915b70329ba2b3fe82da6fec0d83301.9fd6dbfa.png","alt":""},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"second-label","__idx":6},"children":["Second Label"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/second-label.611ad443b45644f64921a49a8a9109168f98a117ba1e3e0e1fa5ae7941a8626e.9fd6dbfa.png","alt":""},"children":[]}]}]},"headings":[{"value":"Multi-Package Shipping","id":"multi-package-shipping","depth":1},{"value":"Requirements","id":"requirements","depth":2},{"value":"Package Types for Multi-Package Shipping","id":"package-types-for-multi-package-shipping","depth":3},{"value":"Example Request & Response","id":"example-request--response","depth":2},{"value":"Label Examples","id":"label-examples","depth":2},{"value":"Master Tracking Label","id":"master-tracking-label","depth":3},{"value":"Second Label","id":"second-label","depth":3}],"frontmatter":{"seo":{"title":"Multi-Package Shipping"}},"lastModified":"2026-04-08T10:47:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/apis/shipengine/docs/shipping/multi-package","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}