Manifest Consignments
Learn how to manifest package data to a carrier via our manifest endpoints.
Manifesting Overview
Once you’ve created a consignment and allocated it to a carrier service, you’re ready to manifest it. This guide explains how to manifest consignments, how to view existing customer manifests, and how to set a consignment as Ready to Ship.
The term “manifesting” refers to collating, formatting and sending consignment data to a carrier. This is the final step of most of shipping workflows.
You can only manifest consignments that are in a state of Allocated, Manifest Failed, or ReadyToShip. If you attempt to manifest a consignment that is not in one of these states then an error is returned.
The Consignments API package has two manifest endpoints:
- Manifest Consignments enables you to manifest multiple consignments at once by providing a list of
{consignmentReferences}. - Manifest Consignments From Query enables you to manifest all consignments that meet a specified set of search criteria.
Manifesting a consignment will change it’s state to Manifested. At this point the carrier is aware of the consignment, and will collect it unless otherwise advised. In order to prevent the consignment being shipped, you would need to either cancel or deallocate it.
For more information on cancelling consignments, see the cancel a consignment guide.
For more information on deallocating consignments, see the deallocate a consignments page.
At this point, you should also print a label for the consignment, if you have not already done so. See our generate labels for packages guide for an explanation of how to get package labels.
Manifest consignments
The simplest way to manifest consignments is to use the Manifest Consignment endpoint. Manifest Consignment enables you to manifest multiple consignments at once by providing their ConsignmentReferences.
To call Manifest Consignments, send a PUT request to https://api.electioapp.com/consignments/manifest. The body of the request should contain a ConsignmentReferences list.
Once the Consignments platform has received the request, it attempts to manifest the consignments listed in the request. The system then returns an array of messages indicating whether each individual consignment was successfully manifested.
Examples
The example shows a request to manifest three consignments. The response indicates that all three consignments were successfully manifested.
PUT https://api.electioapp.com/consignments/manifest
{
"ConsignmentReferences": [
"EC-000-05A-Z6S",
"EC-000-083-45D",
"EC-000-A04-0DV"
]
}
Manifest consignments response
[
{
"IsSuccess": true,
"Message": "Consignment EC-000-002-5FG has been manifested successfully.",
"Data": "EC-000-002-5FG",
"ApiLinks": [
{
"Rel": "Link",
"Href": "https://api.electioapp.com/consignments/EC-000-002-5FG"
}
]
},
{
"IsSuccess": true,
"Message": "Consignment EC-000-002-5FG has been manifested successfully.",
"Data": "EC-000-002-5FG",
"ApiLinks": [
{
"Rel": "Link",
"Href": "https://api.electioapp.com/consignments/EC-000-002-5FG"
}
]
},
{
"IsSuccess": true,
"Message": "Consignment EC-000-002-5FG has been manifested successfully.",
"Data": "EC-000-002-5FG",
"ApiLinks": [
{
"Rel": "Link",
"Href": "https://api.electioapp.com/consignments/EC-000-002-5FG"
}
]
}
]
Manifest consignments using a query
The Manifest Consignments From Query endpoint enables you to manifest consignments using a query, rather than by providing consignment references directly.
To call Manifest Consignments From Query, send a POST request to https://api.electioapp.com/consignments/manifestFromQuery. The body of the request should contain consignment search criteria. You can use the following query fields:
States- The state that the consignments should be in. All the consignments you provide in the request should be in a state of either Allocated, Manifest Failed, or ReadyToShip. If you attempt to manifest a consignment that is not in one of these states then PRO returns an error.Carriers- The carriers that the consignments are allocated to.LabelsPrinted- Whether or not the labels for the consignments have already been printed.ShippingDate- The date that the consignment is scheduled to ship.ShippingDateRanges- A range of scheduled shipping dates.
Once the request is received, Consignments attempts to manifest any packages that meet the specified criteria. Consignments then returns a Message indicating how many consignments met the terms of the query and how many it was able to add to the manifest queue. It also returns a FailedConsignments array listing the consignmentReferences of the consignments unable to queue for manifest.
Set a consignment as ‘Ready to ship’
The Consignments platform’s Set Ready To Ship and Set Not Ready To Ship endpoints can help you when manifesting consignments from queries. These endpoints set a consignment’s consignmentState to ReadyToShip. Although setting a consignment as ready to ship doesn’t alter the consignment in and of itself, it can be useful as a means of marking consignments as ready for manifest via the Manifest Consignments From Query endpoint.
To call Set Ready To Ship, send a PUT request to https://api.electioapp.com/consignments/setreadytoship. The body of the request should comprise a list containing the {consignmentReferences} of all the consignments you want to set as ReadyToShip.
Once the request is received, Consignments changes the consignmentStates of all the relevant consignments to ReadyToShip and returns a confirmation message. You could then manifest these consignments with a simple Manifest Consignments From Query call adding all consignments in that state to the manifest queue.
The example below shows a successful request to set two consignments as ReadyToShip, and a further Manifest Consignments From Query call to manifest all consignments in that state.
PUT https://api.electioapp.com/consignments/setreadytoship
[
"EC-000-05D-EM7",
"EC-000-05D-EKV"
]
[
{
"IsSuccess": true,
"Message": "Consignment marked as Ready To Ship completed successfully",
"Data": "EC-000-05D-EM7",
"ApiLinks": [
{
"Rel": "detail",
"Href": "https://api.electioapp.com/consignments/EC-000-05D-EM7"
}
]
},
{
"IsSuccess": true,
"Message": "Consignment marked as Ready To Ship completed successfully",
"Data": "EC-000-05D-EKV",
"ApiLinks": [
{
"Rel": "detail",
"Href": "https://api.electioapp.com/consignments/EC-000-05D-EKV"
}
]
}
]
POST https://api.electioapp.com/consignments/manifestFromQuery
{
"States": [
"ReadyToShip"
]
}
The Set Not Ready To Ship endpoint works in exactly the same way as Set Ready To Ship, only in reverse. It takes the consignmentReferences of consignments in a ReadyToShip state and returns them to a state of Allocated, enabling them to be deallocated (and subsequently edited if required) or cancelled.
To call Set Not Ready To Ship, send a PUT request to https://api.electioapp.com/consignments/setnotreadytoship. The body of the request should comprise a list containing the {consignmentReferences} of all the consignments you want to return to an Allocated state.
The example below shows a successful Set Not Ready To Ship request for a single consignment.
Example: ‘Not ready to ship’ request
PUT https://api.electioapp.com/consignments/setnotreadytoship
[
"EC-000-05D-GHR"
]
[
{
"IsSuccess": true,
"Message": "Consignment set back to Allocated from Ready To Ship completed successfully",
"Data": "EC-000-05D-GHR",
"ApiLinks": [
{
"Rel": "detail",
"Href": "https://api.electioapp.com/consignments/EC-000-05D-GHR"
}
]
}
]
Manifest consignments from query example
The example shows a request to manifest all consignments that are allocated to Carrier X, shipping from a location with the ShippingLocationReference Location1, and have already had their labels printed. The response indicates that the Consignments platform found 10 consignments meeting these criteria, and that all 10 were successfully queued for manifest.
Example: Manifest from query request
POST https://api.electioapp.com/consignments/manifestFromQuery
{
"ShippingLocationReferences": [
"Location1"
],
"States": [
"Allocated"
],
"Carriers": [
"CARRIER_X"
],
"LabelsPrinted": true
}
‘Manifest from query’ response
{
"Message": "Query found 10 consignment(s). 10 successfully queued to manifest. 0 failed to be added to the queue"
}
Retrieve customer manifests
The Consignments platform has two endpoints that enable you to retrieve current customer manifest details:
- Get Customer Manifests enables you to retrieve a summary of all current manifests.
- Get Customer Manifest enables you to download an individual manifest file as a PDF.
Retrieve a manifest summary
To call Get Customer Manifests, send a GET request to https://api.electioapp.com/consignments/customer/manifests.
Once it has received the request, a summary of all current manifests is returned, including the following information:
- The manifest’s unique reference.
- The filename of the manifest.
- The date the manifest was created.
- The name of the carrier.
- The number of bookings on the manifest.
If you added a shippingLocationReference parameter, then the summary only includes manifests that correspond to shipments from that particular shipping location.
Example: Get customer manifests request
This example shows a request for details of all manifests associated with shipping location EDC5-SL1. Consignments has returned a summary of three manifest files.
Get customer manifests request
GET https://api.electioapp.com/consignments/customer/manifests?shippingLocationReference=EDC5-SL1
Get customer manifests response
[
{
"ManifestReference": "3837b862e2ab47de95f11c016f36f072",
"ManifestFileStorageContainer": "electio-carrierbooking-sandbox-upsready-edc5-ups",
"ManifestFileName": "EDC5_SL1-3837b862e2ab47de95f11c016f36f072.pdf",
"ShippingLocationReference": "EDC5-SL1",
"ShippingLocationName": null,
"Created": "2019-09-16T09:09:56.9894014+00:00",
"CarrierName": "Ups",
"BookingsCount": 1,
"ManifestFileNameSentToCarrier": null
},
{
"ManifestReference": "ffe8739761624fc695e3fbcb72a63557",
"ManifestFileStorageContainer": "electio-carrierbooking-sandbox-upsready-edc5-ups",
"ManifestFileName": "EDC5_SL1-ffe8739761624fc695e3fbcb72a63557.pdf",
"ShippingLocationReference": "EDC5-SL1",
"ShippingLocationName": null,
"Created": "2019-08-15T12:20:06.5067094+00:00",
"CarrierName": "Ups",
"BookingsCount": 1,
"ManifestFileNameSentToCarrier": null
},
{
"ManifestReference": "49fcade22cf24458b1314704a4102738",
"ManifestFileStorageContainer": "electio-carrierbooking-sandbox-upsready-edc5-ups",
"ManifestFileName": "EDC5_SL1-49fcade22cf24458b1314704a4102738.pdf",
"ShippingLocationReference": "EDC5-SL1",
"ShippingLocationName": null,
"Created": "2019-08-14T09:30:54.4984558+00:00",
"CarrierName": "Ups",
"BookingsCount": 1,
"ManifestFileNameSentToCarrier": null
}
]
Download a manifest file
The Get Customer Manifest endpoint enables you to download an individual manifest file in PDF format. To call Get Customer Manifest, send a GET request to https://api.electioapp.com/consignments/customer/manifest/{manifestReference}, where {manifestReference} is the unique reference of the manifest you want to download.
ManifestReference for a particular manifest by making a Get Customer Manifests request for a summary of existing manifest details. Each manifest summary returned contains a ManifestReference.Once the request is received, the Consignments platform returns the specified manifest file as a base-64 encoded byte array. You will need to decode the file in order to view the label itself. If you are unsure how to do so, see the MDN docs for more information.