Creating Manifests
If you need to manifest labels created using ShipStation, you can do so with our /v2/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 ShipStation, you can review our Manifests & SCAN Forms 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
- Create the manifest
- Download the manifest
Requirements
- You must create your manifest on the same calendar date as the ship date of the labels included in the manifest.
- 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. 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 /v2/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.
GET /v2/labels?created_at_start=2023-11-05T0800:26:59.91Z&created_at_end=2023-11-05T15:26:59.91Z HTTP/1.1 Host: api.shipstation.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.
{ "labels": [ { "label_id": "se-29602037", "status": "completed", "shipment_id": "se-6470112", "ship_date": "2023-11-05T00:00:00Z", "created_at": "2023-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.shipstation.com/v2/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.pdf", "png": "https://api.shipstation.com/v2/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.png", "zpl": "https://api.shipstation.com/v2/downloads/0/VIYxvqt0CEaeE6kVeQq7DQ/label-1049004.zpl", "href": "https://api.shipstation.com/v2/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": "2023-11-05T00:00:00Z", "created_at": "2023-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.shipstation.com/v2/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.pdf", "png": "https://api.shipstation.com/v2/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.png", "zpl": "https://api.shipstation.com/v2/downloads/0/KVAY5M7MG0GvNLCBFBbM9Q/label-1049067.zpl", "href": "https://api.shipstation.com/v2/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.shipstation.com/v2/labels?created_at_end=2023-11-05T20%3A00%3A00.263Z&created_at_start=2023-11-05T00%3A00%3A00.263Z&page=1&page_size=25" }, "last": { "href": "https://api.shipstation.com/v2/labels?created_at_end=2023-11-05T20%3A00%3A00.263Z&created_at_start=2023-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 /v2/manifests
POST /v2/manifests HTTP/1.1 Host: api.shipstation.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.
{ "manifests": [ { "manifest_id": "se-11118", "form_id": "se-11118", "created_at": "2023-11-09T18:21:10.59Z", "ship_date": "2023-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.shipstation.com/v2/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": "2023-11-09T18:21:10.59Z", "ship_date": "2023-11-09T00:00:00Z", "shipments": 1, "warehouse_id": null, "submission_id": "1120014041604946070483", "carrier_id": "se-88270", "manifest_download": { "href": "https://api-stage.shipstation.com/v2/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. ShipStation will create a manifest that includes all labels that match the criteria you specify.
| Property | Type | 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. |
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 | required, ISO 8601 Standard The ship date you want to include labels for. Example: `2024-07-25T15:24:46.657Z |
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. |
Each manifest is created for a specific warehouse, so you'll need to provide the warehouse_id rather than the ship_from address. You can create a warehouse for each location that you want to create manifests for.
POST /v2/manifests
POST /v2/manifests HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "carrier_id": "se-123890", "excluded_label_ids": [], "warehouse_id": "se-11921", "ship_date": "2024-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.
{ "manifests": [ { "manifest_id": "se-11119", "form_id": "se-11119", "created_at": "2024-11-09T19:59:22.837Z", "ship_date": "2024-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.shipstation.com/v2/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": "2024-11-09T19:59:22.837Z", "ship_date": "2024-11-09T00:00:00Z", "shipments": 3, "warehouse_id": "se-107273", "submission_id": "9475711201080306735429", "carrier_id": "se-82785", "manifest_download": { "href": "https://api-stage.shipstation.com/v2/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 multiple.
Each manifest includes labels with the same ship_date, carrier_id, and warehouse_id. ShipStation 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 labels for the same warehouse and ship date, ShipStation 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 ShipStation only includes 500 labels per manifest.
Manifests are separated by Ship From addresses. If you do not use warehouses, ShipStation still assigns a warehouse_id to your Ship From address so you can create manifests by Ship From address.
To minimize the number of manifests you need to create, ShipStation matches the manifest addresses to your Ship From addresses. Because each manifest has one Ship From address, we recommend that you have consistent Ship From addresses, like a warehouse.
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 manifests.
{ "manifests": [ { "manifest_id": "se-11116", "form_id": "se-11116", "created_at": "2024-11-09T18:16:09.793Z", "ship_date": "2024-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.shipstation.com/v2/downloads/0/mQ3QZQL6-0SLESTz43Y8vw/manifest-11116.pdf" } }, { "manifest_id": "se-11117", "form_id": "se-11117", "created_at": "2024-11-09T18:16:11.233Z", "ship_date": "2024-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.shipstation.com/v2/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": "2024-11-09T18:16:09.793Z", "ship_date": "2024-11-09T00:00:00Z", "shipments": 1, "warehouse_id": null, "submission_id": "9475711201080306528571", "carrier_id": "se-82785", "manifest_download": { "href": "https://api-stage.shipstation.com/v2/downloads/0/mQ3QZQL6-0SLESTz43Y8vw/manifest-11116.pdf" }, "label_ids": [ "se-1050621", "se-1050622" ], "request_id": "9367f24f-9aa6-4358-8dd7-a73bb38e8870", "errors": [], }
Example Error Response
If no labels meet the specified criteria, you will get a response similar to the one below.
{ "request_id": "47b3f327-2dd1-4e24-8570-cda6fba8a00f", "errors": [ { "error_source": "shipstation", "error_type": "system", "error_code": "unspecified", "message": "No labels were found matching the given criteria." } ] }
Download the Manifest
Now that you've created the manifest(s), you have a URL to download the manifest PDF.
You can enter this value directly in a web browser to view and download the file, or you 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.
GET https://api.shipstation.com/v2/downloads/0/BpP_fo0d9EiiQJ7hqDQGmA/manifest-11102.pdf HTTP/1.1 Host: api.shipstation.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.
You may use either the label_ids property or the excluded_label_ids property but not both. If you use the excluded_label_ids property, you must also include the carrier_id, warehouse_id, and ship_date in your request.