Site Logo

Creating a Manifest

If you need to manifest labels created using ShipEngine, you can do so with our **/v1/manifests/ endpoint. This guide will walk you through the steps for creating a daily manifest.

To learn more about what manifests are, why they are useful, and how they work in ShipEngine, you can review our Manifests overview page.

A common manifest workflow has three main tasks:

  • Determine which labels to include in the manifest and how you want to specify them in your request to ShipEngine
  • Create the manifest
  • Download the manifest

Requirements

  • You must create your manifest on the same calendar date as the date on which the labels included in the manifest were created.
  • You must have either the label_ids (for explicit manifests) or the properties you wish to use as criteria (for implicit manifests) in your request.

Determine Which Labels to Manifest

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. In this example, we'll use the simple case of creating a manifest for all labels created today.

To get a list of the labels that were created today, we will use the list labels endpoint and pass some query parameters to filter the data.

Example Request & Response

GET /v1/labels

In this example, we'll use created_at_start and created_at_end query parameters. 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.

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

Response

Depending on how many labels were created in this time range, we could expect a very long response. In this example, we truncate the response to just 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
151
{
  "labels": [
    {
      "label_id": "se-29602037",
      "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-29544722",
      "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

When creating a manifest, you can explicitly or implicitly specify which labels to include in a manifest.

  • Explicit manifests specify exactly which labels to include in the manifest with an array of label_ids. You may specify up to 500 labels in a single manifest.
  • Implicit manifests specify criteria for including labels in the manifest by adding the desired properties to the request body.

We've included examples of both types below.

Explicit Manifest Example

Using the two labels from the above GET labels request + one additional label, this request creates a manifest explicitly for these three labels.

POST /v1/manifests

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-29602037", "se-29544722", "se-29475869"]
}

Response

Each manifest contains an href property with a URL where you can downlaod the manifest. There is also a top-level href property that will contain the URL for the first manifest if more than one is returned.

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
{
  "manifests": [
    {
      "manifest_id": "se-11118",
      "form_id": "se-11118",
      "created_at": "2020-11-09T18:21:10.59Z",
      "ship_date": "2020-11-09T00:00:00Z",
      "shipments": 3,
      "label_ids": [
        "se-29602037",
        "se-29544722",
        "se-29475869"
      ],
      "warehouse_id": null,
      "submission_id": "1120014041604946070483",
      "carrier_id": "se-88270",
      "manifest_download": {
        "href": "https://api-stage.shipengine.com/v1/downloads/0/pj37Bb5hi0qdslHc7_wCVQ/manifest-11118.pdf"
      }
    }
  ],
  "manifest_requests": [
    {
      "manifest_request_id": "se-28529731",
      "status": "in_progress"
    }
  ],
    "manifest_id": "se-11118",
    "form_id": "se-11118",
    "created_at": "2020-11-09T18:21:10.59Z",
    "ship_date": "2020-11-09T00:00:00Z",
    "shipments": 1,
    "warehouse_id": null,
    "submission_id": "1120014041604946070483",
    "carrier_id": "se-88270",
    "manifest_download": {
     "href": "https://api-stage.shipengine.com/v1/downloads/0/pj37Bb5hi0qdslHc7_wCVQ/manifest-11118.pdf"
    },
    "label_ids": [
      "se-29602037",
      "se-29544722",
      "se-29475869"
    ],
    "request_id": "7de36d42-8343-4247-95ce-153d8b615d1f",
    "errors": [],
}

Implicit Manifest Example

You may instead want to create a manifest that includes all the labels that match specific criteria. Labels that do not meet the specified criteria will be excluded from the manifest.

You may specify values for one or more of the properties below. ShipEngine will create a manifest that includes all labels that match the criteria you specify.

PropertyTypeDescription
carrier_idstringrequired
The carrier ID you wish to create a manifest for. This will exclude labels that do not use this specified carrier_id.
warehouse_idstringrequired
The Warehouse ID this manifest is being created for. This will exclude labels that do not use the specified warehouse_id.
ship_datedate stringrequired, ISO 8601 Standard
The ship date you want to include labels for. Example: 2019-07-25T15:24:46.657Z
excluded_label_idsstring arrayThe label_ids that you do NOT wish to manifest, even if they meet the rest of the specified criteria.

POST /v1/manifests

1
2
3
4
5
6
7
8
9
10
11
POST /v1/manifests HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "carrier_id": "se-123890",
  "excluded_label_ids": [],
  "warehouse_id": "se-11921",
  "ship_date": "2019-07-25T05:00:00.000Z"
}

Response

As is the case with the explicit manifests, each manifest contains an href property with a URL to downlaod the manifest.

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
{
    "manifests": [
        {
            "manifest_id": "se-11119",
            "form_id": "se-11119",
            "created_at": "2020-11-09T19:59:22.837Z",
            "ship_date": "2020-11-09T00:00:00Z",
            "shipments": 3,
            "label_ids": [
                "se-1050678",
                "se-1050679",
                "se-1050680"
            ],
            "warehouse_id": "se-107273",
            "submission_id": "9475711201080306735429",
            "carrier_id": "se-82785",
            "manifest_download": {
                "href": "https://api-stage.shipengine.com/v1/downloads/0/WPZ_DNt2dUKPX4L9pOh71g/manifest-11119.pdf"
            }
        }
    ],
    "manifest_requests": [
     {
      "manifest_request_id": "se-28529731",
      "status": "in_progress"
     }
    ],
    "manifest_id": "se-11119",
    "form_id": "se-11119",
    "created_at": "2020-11-09T19:59:22.837Z",
    "ship_date": "2020-11-09T00:00:00Z",
    "shipments": 3,
    "warehouse_id": "se-107273",
    "submission_id": "9475711201080306735429",
    "carrier_id": "se-82785",
    "manifest_download": {
        "href": "https://api-stage.shipengine.com/v1/downloads/0/WPZ_DNt2dUKPX4L9pOh71g/manifest-11119.pdf"
     },
    "label_ids": [
        "se-1050678",
        "se-1050679",
        "se-1050680"
    ],
    "request_id": "ed87e59c-bd95-468b-a4fb-5b55e8630df9",
    "errors": [],
}

About the Manifest Response

In the above examples, the responses included a single manifest. However, your response could include more than one manifest.

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. For example, if you specify label_ids for USPS and FedEx for the same warehouse and ship date, ShipEngine will return two manifests - one for USPS labels with the specified warehouse and ship date and one for FedEx labels with the specified warehouse and ship date.

You can also receive multiple manifests in the response if your request includes more than 500 labels since ShipEngine only includes 500 labels per manifest.

Response with Multiple Manifests

If the response you receive is split into multiple manifests, you'll notice that each manifest object contains an href property with a URL where you can download a PDF version of the manifest. There is also a top-level href that includes a URL where you can download the first manifest if multiple manifests are returned. Each manifest object indicates the specific label_ids that are included in the manifest.

This example response includes two manifest objects.

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
{
  "manifests": [
    {
      "manifest_id": "se-11116",
      "form_id": "se-11116",
      "created_at": "2020-11-09T18:16:09.793Z",
      "ship_date": "2020-11-09T00:00:00Z",
      "shipments": 1,
      "label_ids": [
        "se-1050621"
      ],
      "warehouse_id": null,
      "submission_id": "9475711201080306528571",
      "carrier_id": "se-82785",
      "manifest_download": {
        "href": "https://api-stage.shipengine.com/v1/downloads/0/mQ3QZQL6-0SLESTz43Y8vw/manifest-11116.pdf"
      }
    },
    {
      "manifest_id": "se-11117",
      "form_id": "se-11117",
      "created_at": "2020-11-09T18:16:11.233Z",
      "ship_date": "2020-11-09T00:00:00Z",
      "shipments": 1,
      "label_ids": [
        "se-1050622"
      ],
      "warehouse_id": null,
      "submission_id": "1120014041604945770433",
      "carrier_id": "se-88270",
      "manifest_download": {
        "href": "https://api-stage.shipengine.com/v1/downloads/0/5GOUrT4TRkWgygJyvJt0kA/manifest-11117.pdf"
      }
    }
  ],
    "manifest_requests": [
     {
      "manifest_request_id": "se-28529731",
      "status": "in_progress"
     }
    ],
  "manifest_id": "se-11116",
  "form_id": "se-11116",
  "created_at": "2020-11-09T18:16:09.793Z",
  "ship_date": "2020-11-09T00:00:00Z",
  "shipments": 1,
  "warehouse_id": null,
  "submission_id": "9475711201080306528571",
  "carrier_id": "se-82785",
  "manifest_download": {
    "href": "https://api-stage.shipengine.com/v1/downloads/0/mQ3QZQL6-0SLESTz43Y8vw/manifest-11116.pdf"
  },
  "label_ids": [
    "se-1050621",
    "se-1050622"
  ],
  "request_id": "9367f24f-9aa6-4358-8dd7-a73bb38e8870",
  "errors": [],
}

Download the Manifest

Now that we've created the manifest(s), we have a URL to download the manifest PDF from.

We can enter this value directly in a web browser to view and download the file, 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 Accept-type: 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

Group Labels into Multiple Manifests

If you have multiple outgoing shipments per day, you may want to group your daily labels into more than one manifest.

You can use either the label_ids property or the excluded_label_ids property to group or control which labels are included in each manifest and avoid overlap. A label should be included in only one manifest.