Creating a Manifest

Manifests are required by some carriers to streamline the pickup process by allowing them to process many shipments at once. Without a manifest, the carrier would need to scan each package individually. When picking up hundreds of packages from a warehouse, scanning a manifest is far more efficient than scanning each individual package.

This guide walks you through creating a daily manifest.

Get the List of Labels

The first step in creating a manifest is determining which labels to include in the manifest and the best way to specify them in your request to ShipEngine. Let's start with the simple case of creating a manifest for all labels that were created today.

To get a list of the labels that were created today, we will use the /v1/labels endpoint and pass some query parameters to filter the data. In this case we pass created_at_start and created_at_end. These parameters define a time range and allow us to get the list of labels that were created on a particular business day. Without these parameters, this endpoint will return all labels.

Example Request

This example gets a list of all the labels that were created between the created_at_start_time and the created_at_end_time. It sends an HTTP GET request to the /v1/labels endpoint and passes URL parameters to filter the labels that are returned.

1
2
3
4
GET /v1/labels?created_at_start=2020-11-05T0800:26:59.91Z&created_at_end=2020-11-05T15:26:59.91Z HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

Example Response

This is an example of the response that is returned from request above. It includes two 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
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
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
{
  "labels": [
    {
      "label_id": "se-1049004",
      "status": "completed",
      "shipment_id": "se-6470112",
      "ship_date": "2020-11-05T00:00:00Z",
      "created_at": "2020-11-05T14:26:59.91Z",
      "shipment_cost": {
        "currency": "usd",
        "amount": 3.18
      },
      "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
      },
      "tracking_number": "9400111899223674205955",
      "is_return_label": false,
      "rma_number": null,
      "is_international": false,
      "batch_id": "",
      "carrier_id": "se-82785",
      "service_code": "usps_first_class_mail",
      "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": "stamps_com",
      "tracking_status": "in_transit",
      "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.pdf",
        "png": "https://api.shipengine.com/v1/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.png",
        "zpl": "https://api.shipengine.com/v1/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.zpl",
        "href": "https://api.shipengine.com/v1/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.pdf"
      },
      "form_download": null,
      "insurance_claim": null,
      "packages": [
        {
          "package_code": "package",
          "weight": {
            "value": 1.00,
            "unit": "ounce"
          },
          "dimensions": {
            "unit": "inch",
            "length": 0.0,
            "width": 0.0,
            "height": 0.0
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.00
          },
          "tracking_number": "9400111899223674205955",
          "label_messages": {
            "reference1": null,
            "reference2": null,
            "reference3": null
          },
          "external_package_id": null
        }
      ],
      "charge_event": "carrier_default"
    },
      "label_id": "se-1049067",
      "status": "completed",
      "shipment_id": "se-6470260",
      "ship_date": "2020-11-05T00:00:00Z",
      "created_at": "2020-11-05T16:53:41.127Z",
      "shipment_cost": {
        "currency": "usd",
        "amount": 3.18
      },
      "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
      },
      "tracking_number": "9400111899223674665629",
      "is_return_label": false,
      "rma_number": null,
      "is_international": false,
      "batch_id": "",
      "carrier_id": "se-82785",
      "service_code": "usps_first_class_mail",
      "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": "stamps_com",
      "tracking_status": "in_transit",
      "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.pdf",
        "png": "https://api.shipengine.com/v1/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.png",
        "zpl": "https://api.shipengine.com/v1/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.zpl",
        "href": "https://api.shipengine.com/v1/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.pdf"
      },
      "form_download": null,
      "insurance_claim": null,
      "packages": [
        {
          "package_code": "package",
          "weight": {
            "value": 1.00,
            "unit": "ounce"
          },
          "dimensions": {
            "unit": "inch",
            "length": 0.0,
            "width": 0.0,
            "height": 0.0
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.00
          },
          "tracking_number": "9400111899223674665629",
          "label_messages": {
            "reference1": null,
            "reference2": null,
            "reference3": null
          },
          "external_package_id": null
        }
      ],
      "charge_event": "carrier_default"
    }
  ],
  "total": 2,
  "page": 1,
  "pages": 1,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/labels?created_at_end=2020-11-05T20%3A00%3A00.263Z&created_at_start=2020-11-05T00%3A00%3A00.263Z&page=1&page_size=25"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/labels?created_at_end=2020-11-05T20%3A00%3A00.263Z&created_at_start=2020-11-05T00%3A00%3A00.263Z&page=1&page_size=25"
    },
    "prev": {},
    "next": {}
  }
}

Create the Manifest

In the response above, you can see that two labels were returned. We can create an explicit manifest that includes the two label_id values from the response above.

Example Request

This example creates a manifest by making an HTTP POST request to the /v1/manifests endpoint. It sets the values of the label_ids property to the label_id values from the response above.

1
2
3
4
5
6
7
8
POST /v1/manifests HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "label_ids": ["se-1049004", "se-1049067"]
}

Example Response

This is an example of the response that is returned from the request above. In this case, it only returns one manifest, but it could return more than one.

Each manifest includes labels with the same ship_date, carrier_id, and warehouse_id. ShipEngine will create multiple manifests if you send labels with different values for those properties. You might also have multiple manifests in the response if your request includes more than 500 labels since ShipEngine only includes 500 labels per manifest.

Notice that the manifest object has an href property that contains a URL. You can use this URL to download the manifest. There is also a top-level href property that is set to the href of the first manifest if the response contains more than one manifest. In our case, both properties contain the same value since only one manifest was created.

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
{
  "manifests": [
    {
      "manifest_id": "se-11102",
      "form_id": "se-11102",
      "created_at": "2020-11-05T16:39:34.503Z",
      "ship_date": "2020-11-05T00:00:00Z",
      "shipments": 1,
      "label_ids": [
        "se-1049004",
        "se-1049067"
      ],
      "warehouse_id": null,
      "submission_id": "9475711201080308027034",
      "carrier_id": "se-82785",
      "manifest_download": {
        "href": "https://api.shipengine.com/v1/downloads/0/BpP_fo0d9EiiQJ7hqDQGmA/manifest-11102.pdf"
      }
    }
  ],
  "request_id": "95c1dbc4-0819-4f01-91c5-87183c820b54",
  "errors": [],
  "manifest_id": "se-11102",
  "form_id": "se-11102",
  "created_at": "2020-11-05T16:39:34.503Z",
  "ship_date": "2020-11-05T00:00:00Z",
  "shipments": 1,
  "label_ids": [
    "se-1049004",
    "se-1049067"
  ],
  "warehouse_id": null,
  "submission_id": "9475711201080308027034",
  "carrier_id": "se-82785",
  "manifest_download": {
    "href": "https://api.shipengine.com/v1/downloads/0/BpP_fo0d9EiiQJ7hqDQGmA/manifest-11102.pdf"
  }
}

Download the Manifest

At this point, we've created the manifest. We now have a URL where we can download the manifest, which is a PDF file.

We can enter this value directly in a web browser to view and download the file through the browser, or we can download it programmatically.

Example Request

This example downloads the manifest using the URL returned in the response above. Notice that you must change the Content-Type to application/pdf.

1
2
3
4
GET https://api.shipengine.com/v1/downloads/0/BpP_fo0d9EiiQJ7hqDQGmA/manifest-11102.pdf HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Accept-Type: application/pdf