Background
A common shipping requirement for a Peoplevox user is to support "multi-package consignments". This requirement is a scenario where an end carrier is aware that two or more packages are expected under a shared consignment reference, usually going to the same customer and address. "Multi-package consignments" often attract a commercially incentivised offering from the carrier (versus two separate consignments) as well as representing an improved experience for the end consumer, who often receives a lead tracking number under which they can track all packages.
The Peoplevox Carrier Integration API request / response workflow is triggered per package—this term means that each request only contains a single package, triggered at the point of package creation.
Note: This approach can contrast with how many Carrier Management Systems (CMS) and carriers structure their integrations, often expecting a single request defining all packages.
Implementing Multi-Package Consignment Shipping with Peoplevox
The suggested approach to supporting multi-package consignment shipping with Peoplevox would see a draft/cached shipment created by the Carrier Integration API endpoint, with that draft/cached shipment then being appended with additional packages until the order was fully shipped from Peoplevox. Once the order was fully shipped, the draft shipment should be confirmed with all labels being returned to Peoplevox for all packages together. Please see the diagram:
To help you understand if an order is fully shipped, the following fields can be used from the Carrier Integration API schema 2.0 request:
{
"despatchPackage": {
"despatch": {
"salesOrder": {
"totalPickedItems": 3,
"totalDespatchedItems": 3,
...
}
...
},
...
},
...
}
Evaluating if totalPickedItems is less than totalDespatchedItems allows an endpoint to understand if the order is now shipped completely, or if more packages could be expected.
Each received request contains one package, allowing a draft / cached shipment to be created, with packages appended with each additional request from Peoplevox (using a unique identifier such as the despatchPackageId or the packageNumber to ensure no duplication of packages in edge case scenarios).
While totalPickedItems is less than totalDespatchedItems, the endpoint can simply update the draft / cached shipment. The response in each case can define the 'status' value for the print request as 'not required' which ensures Peoplevox knows it doesn't need to print any labels for this package (at this time).
Once totalPickedItems is equal to totalDespatchedItems, the endpoint still needs to update the draft / cached shipment, but this time is also able to process the complete shipment. Any URLs returned to Peoplevox to print documentation (e.g., shipping labels) should be to a single file, but this file can contain multiple pages as necessary.
Example Response for Initial Package(s)
Initial package requests should be consumed by the endpoint, with response indicating a 'success' status with print requests 'not required'. In most cases, it would be expected that the trackingNumber array is also empty.
{
"status": "success",
"message": null,
"data": {
"trackingNumbers": [],
"newPrintRequests": [
{
"printRequestId": 1,
"printTemplateUrl": null,
"status": "not required"
}
]
}
}Example Response for Final Package
For the final package, the endpoint should return a multi-page PDF for all documents required in each documentReference. Should it be required, an optional parameter despatchPackageId can be provided in the trackingNumber array elements in order to retrospectively update previously shipped packages.
{
"status": "success",
"message": null,
"data": {
"trackingNumbers": [
{
"despatchPackageId" : 1,
"trackingType": "outbound",
"trackingNumber": "TRCK123456788"
},
{
"despatchPackageId" : 2,
"trackingType": "outbound",
"trackingNumber": "TRCK123456789"
}
],
"newPrintRequests": [
{
"printRequestId": 2,
"printTemplateUrl": "https://mycarrierintegrationhost.com/labels/combined_package_1_and_2_labels.pdf,
"status": "success"
}
]
}
}Alternative Approaches
Some carrier management (CMS) platforms and carriers support the ability to append an existing consignment, even after a label has been generated. Where this ability is possible, each package shipped from Peoplevox can be appended to an existing un-manifested consignment for the same order, without affecting any previously generated labels.
Note: Such 'consignment appendment' functionality isn't widely available and is typically reserved for a small number of carriers or for CMS platforms that communicate with end carriers via EDI (e.g., end of day manifest).