# 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](/manifests-scanforms). 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](/list-labels) 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. ```http 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. ```json { "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** ```http 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. ```json { "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](/list-carriers) 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](https://en.wikipedia.org/wiki/ISO_8601) 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** ```http 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. ```json { "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. ```json { "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. ```json { "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`. ```http 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.