Explicit vs Implicit Manifests

If your carrier requires a physical manifest, you will need to send a request to ShipEngine to create it. You can send a request with a list of specific labels to include in an explicit manifest.

Alternately, you can include filter criteria in your request and allow ShipEngine to determine the exact list of labels to include in an implicit manifest, including a property that allows you to exclude labels from the manifest even if they meet the filter criteria.

Explicit Manifests

One way to create manifests in ShipEngine is to explicitly specify which labels to include in the manifest.

To create an explicit manifest, you only need to set a single field:

Field Name	Type	Required?	Description
`label_ids`	array of strings	yes	Use this to specify the labels that you want to include in the manifest. You may specify up to 500 labels in a single manifest.

Example Request

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"]
}

Example Response

Notice that the response includes an array of manifests. The request may return more than one manifest. Each manifest contains an href property containing a URL where the manifest can be downloaded. 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
{
  "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"
      }
    }
  ],
  "request_id": "7de36d42-8343-4247-95ce-153d8b615d1f",
  "errors": [],
  "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,
  "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"
  }
}

Example Response with Multiple Manifests

This response includes two manifest objects. ShipEngine will automatically split your labels across multiple manifests if you have more than 500 labels in the request or if the specified label_ids span multiple carriers, warehouses, or ship dates.

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.

Each manifest object contains an href property that contains 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.

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
{
  "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"
      }
    }
  ],
  "request_id": "9367f24f-9aa6-4358-8dd7-a73bb38e8870",
  "errors": [],
  "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",
    "se-1050622"
  ],
  "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"
  }
}

Implicit Manifests

You may also create a manifest that includes all the labels that match the specific criteria you specify in the request. 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 this criteria.

You can use the excluded_label_ids property to specify label IDs that should be excluded from the manifest even if they match the specified criteria.

Property	Description
`carrier_id`	string, required The carrier ID you wish to create a manifest for. This will exclude labels that do not use this specified `carrier_id`.
`excluded_label_ids`	string array The label IDS that you do NOT wish to manifest, even if they meet the rest of the specified criteria.
`warehouse_id`	string, required The Warehouse ID this manifest is being created for. This will exclude labels that do not use the specified `warehouse_id`.
`ship_date`	date string, (ISO 8601 Standard), required The ship date you want to include labels for. Example: `2019-07-25T15:24:46.657Z`

Example Request

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"
}

Example Response

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
{
    "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"
            }
        }
    ],
    "request_id": "ed87e59c-bd95-468b-a4fb-5b55e8630df9",
    "errors": [],
    "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"
    }
}

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 your control which labels are included in each manifest and avoid overlap. A label should be included in only one manifest.