Site Logo

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.
    • Popular carriers that have multi-package services include FedEx, UPS, DHL Express, DHL Express Canada, DHL Express UK, FirstMile, and Purolator Canada.

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 /v1/labels

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
POST /v1/labels HTTP/1.1
Host: api.shipengine.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",
      "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"
    },
    "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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
{
    "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.shipengine.com/v1/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.pdf",
        "zpl": "https://api.shipengine.com/v1/downloads/10/WJe_Vy3P20K8TUEt-a_5YQ/label-120646641.zpl",
        "href": "https://api.shipengine.com/v1/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.shipengine.com/v1/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.pdf",
                "png": "https://api.shipengine.com/v1/downloads/10/e1CdkA2cKEmtkFTHl5Jpjw/labelpackage-127246591.png",
                "zpl": "https://api.shipengine.com/v1/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.shipengine.com/v1/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.pdf",
                "png": "https://api.shipengine.com/v1/downloads/10/eJHEkrjJx0C3TA1lE_U3ww/labelpackage-127246592.png",
                "zpl": "https://api.shipengine.com/v1/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

This is the master tracking label, the first label in the series.

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.