The Request entity describes three key pieces of data:
Metadata about the rest of the request, which specifies schema version numbers
A despatchPackage, which represents the physical shipment for which documentation is requested
oldPrintRequests, which describes the collection of documents that have been requested for the package
The metadata specifies version numbers for various properties of the integration.
schemaVersion: This defines the version of the JSON schema for the Request entity. All future versions will include the metadata node, but future versions of the schema may add, remove, rearrange or rename other properties of the request. The schemaVersion property allows your endpoint to determine how to parse the rest of the request.
platformVersion: This defines the version number of the Peoplevox carrier platform itself. This describes the non-schema properties of the connection. For example, in the v1.1 implementation, the ability to capture a service type selection from the response was added. A request using platformVersion 1.1 indicates that the platform is capable of that functionality.
documentBundleEndpointVersion: This defines the version number of the facade interface that your endpoint implements. Future versions of the facade may introduce new constraints on the way in which your endpoint accepts or responds to requests from the platform, for example v1.1 introduced the ability to respond with a service type selection in addition to the tracking data and label URLs. This involved the addition of a new optional property on the response.
Changes within a major version number are not breaking. For example if you originally integrate using the 1.0 schema, nothing will be introduced in subsequent 1.x versions that will break your integration. Future 1.x versions may however contain additional properties or functionality, and you may need to update your integration if you wish to make use of those.
The despatchPackage contains the details of the package to be shipped. It includes the carrier and service level, the destination address, dimensions, and details of the products inside it. It also contains a reference to the original sales order.
The oldPrintRequests contains the collection of documents that the user in Peoplevox has requested from your integration. Each of these contains a reference that links back to the documentation types that you indicated your integration can support. For example, if you indicate that you support a document type called “foo”, then this collection can contain documentReferences of “foo”.
Version 2.0 (Stable)
Version 2.0 is a breaking change from previous versions. Both this and v1.x are still supported, and when setting up your connection details in Peoplevox, you can choose which version to use.
This version rearranges and renames a number of properties for clarity and to better represent their relationships with other entities. It also introduces some more granular data around kitting relationships, as well as exposing the name of the print terminal against print requests.
When should I use this version?
Use this version if any of the following apply to you:
You are writing a new integration to the platform
You need data to know from where in the warehouse (which print station) the request originated
You need information about kitting relationships on the request
Request schema
{
"metadata": {
"schemaVersion": "2.0",
"platformVersion": "2.0",
"documentBundleEndpointVersion": "1.1"
},
"despatchPackage": {
"despatchPackageId": 1,
"despatch": {
"despatchNumber": "DES100",
"carrier": {
"name": "Royal Mail",
"reference": "RM"
},
"serviceType": {
"name": "Royal Mail Next Day",
"code": "RM24",
"outboundReference": "EXT_RM24"
},
"loadReference": "",
"salesOrder": {
"salesOrderNumber": "SO100",
"customer": {
"name": "Matt Thomson",
"reference": "123456789",
"firstName": "Matt",
"lastName": "Thomson",
"phone": "",
"mobile": "",
"email": "matt.thomson@peoplevox.com",
"creditLimit": "",
"paymentTerm": ""
},
"customerPurchaseOrderReferenceNumber": "",
"shippingAddress": {
"line1": "119",
"line2": "Marylebone Road",
"townCity": "London",
"region": "",
"postCode": "NW1 5PU",
"countryName": "United Kingdom",
"countryCode": "UK",
"companyName": "Descartes"
},
"invoiceAddress": {
"line1": "119",
"line2": "Marylebone Road",
"townCity": "London",
"region": "",
"postCode": "NW1 5PU",
"countryName": "United Kingdom",
"countryCode": "UK",
"companyName": "Descartes"
},
"requestedDeliveryDate": "01/01/2018 00:00:00",
"shippingCost": "0.00",
"email": "matt.thomson@peoplevox.com",
"contactName": "Matt Thomson",
"paymentMethod": "Cash",
"totalSale": "0.00",
"discount": "0.00",
"taxPaid": "0.00",
"createdDate": "",
"channelName": "My website",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"site": "PrimarySite",
"currency": "GBP",
"termsOfTrade": "DDP",
"customsRegistrationNumber": "EoriNumbersOrSimilar",
"iossNumber": "YourIossNumber",
"deliveryNotes": "Leave at door, for example",
"contentsType": "Merchandise, for example",
"status": "Despatched",
"totalPickedItems": 3,
"totalDespatchedItems": 3
}
},
"weight": "0.00",
"weightMeasure": "lb",
"height": "0.00",
"heightMeasure": "in",
"width": "0.00",
"widthMeasure": "in",
"depth": "0.00",
"depthMeasure": "in",
"packageType": {
"name": "",
"barcode": ""
},
"packageNumber": 1,
"carrier": {
"name": "Royal Mail",
"reference": "RM"
},
"serviceType": {
"name": "Royal Mail Next Day",
"code": "RM24",
"outboundReference": "EXT_RM24"
},
"items": [
{
"container": {
"barcode": "",
"reference": ""
},
"itemType": {
"itemCode": "KitParentA",
"name": "Kit A",
"barcode": "KIT001",
"description": "This is a lovely kit",
"itemGroup": "Widget Kits",
"unitOfMeasure": {
"name": "Unit",
"symbol": "EA"
},
"defaultSupplierPartNumber": "MYKITA",
"buyPrice": "0.00",
"wholesalePrice": "0.00",
"retailPrice": "0.00",
"weight": "3.00",
"weightMeasure": "kg",
"height": "3.00",
"width": "1.00",
"depth": "1.00",
"dimensionMeasure": "cm",
"tags": "",
"taxCode": "",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"attribute6": "",
"attribute7": "",
"attribute8": "",
"attribute9": "",
"attribute10": "",
"attribute11": "",
"attribute12": "",
"attribute13": "",
"attribute14": "",
"attribute15": "",
"hsCode": "6101",
"countryOfOrigin": "GBR",
"dryIce": false,
"medicalDryIce": false,
"alcohol": false,
"hazardous": false
},
"salePrice": "20.00",
"salesOrderItemAttribute1": "",
"salesOrderItemAttribute2": "",
"salesOrderItemAttribute3": "",
"salesOrderItemLine": "1",
"quantity": 1,
"components": [
{
"itemType": {
"itemCode": "ItemA",
"name": "Item A",
"barcode": "ITEMA001",
"description": "This is a lovely widget",
"itemGroup": "Widgets",
"unitOfMeasure": {
"name": "Unit",
"symbol": "EA"
},
"defaultSupplierPartNumber": "MYWIDGETA",
"buyPrice": "0.00",
"wholesalePrice": "0.00",
"retailPrice": "0.00",
"weight": "1.00",
"weightMeasure": "kg",
"height": "1.00",
"width": "1.00",
"depth": "1.00",
"dimensionMeasure": "cm",
"tags": "",
"taxCode": "",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"attribute6": "",
"attribute7": "",
"attribute8": "",
"attribute9": "",
"attribute10": "",
"attribute11": "",
"attribute12": "",
"attribute13": "",
"attribute14": "",
"attribute15": "",
"hsCode": "6101",
"countryOfOrigin": "GBR",
"dryIce": false,
"medicalDryIce": false,
"alcohol": false,
"hazardous": false
},
"quantity": 1
},
{
"itemType": {
"itemCode": "ItemB",
"name": "Item B",
"barcode": "ITEMB001",
"description": "This is another lovely widget",
"itemGroup": "Widgets",
"unitOfMeasure": {
"name": "Unit",
"symbol": "EA"
},
"defaultSupplierPartNumber": "MYWIDGETB",
"buyPrice": "0.00",
"wholesalePrice": "0.00",
"retailPrice": "0.00",
"weight": "1.00",
"weightMeasure": "kg",
"height": "1.00",
"width": "1.00",
"depth": "1.00",
"dimensionMeasure": "cm",
"tags": "",
"taxCode": "",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"attribute6": "",
"attribute7": "",
"attribute8": "",
"attribute9": "",
"attribute10": "",
"attribute11": "",
"attribute12": "",
"attribute13": "",
"attribute14": "",
"attribute15": "",
"hsCode": "6101",
"countryOfOrigin": "GBR",
"dryIce": false,
"medicalDryIce": false,
"alcohol": false,
"hazardous": false
},
"quantity": 2
}
]
}
]
},
"printRequests": [
{
"printRequestId": 1,
"documentReference": "Carrier label",
"printTerminal": "PackBench001_ZPL"
},
{
"printRequestId": 2,
"documentReference": "Customs documentation",
"printTerminal": "PackBench001_Laserjet"
},
{
"printRequestId": 3,
"documentReference": "Returns label",
"printTerminal": "PackBench001_ZPL"
}
]
}Change log
schemaVersion and platformVersion 1.x -> 2.x:
Renamed the "oldPrintRequests" collection to "printRequests" for clarity
Renamed the old "despatchItems" collection to "items" for clarity
Added the "printTerminal" property to each printRequest entity - this represents the name of the print terminal for which the document was queued (as registered in the Peoplevox Print Service)
-
Restructured the "item" entity to better expose data related to kitted items:
The "item" entity represents the item from the original order that was shipped in the package
The "salePrice", "salesOrderItemAttribute1", "salesOrderItemAttribute2", "salesOrderItemAttribute3", and "salesOrderItemLine" are now properties of that "item" entity, rather than the "itemType" (which is the product definition)
The "item" entity now exposes a "components" collection, which represents the individual kit items that were actually despatched in the package. The quantity against the "item" is the number of those kits shipped, and the quantity against the "component" is how many of those components were shipped. Since the "salePrice" etc. are properties of the item line, these are only displayed against the "item" entity, not against the individual "component" entities
Added the package dimension units to the "despatchPackage" entity (lb / kgs / cm / in) so you no longer have to infer the unit from the "item"
Added "hsCode", "countryOfOrigin", "dryIce", "medicalDryIce", "alcohol", and "hazardous" to the despatchItems.ItemType collection
Added "currency", "termsOfTrade", "customsRegistrationNumber", "iossNumber", "deliveryNotes", and "contentsType" to the salesOrder entity
Added "companyName" to the address entities
Added "totalPickedItems" and "totalDespatchedItems" to assist with multi-parcel shipment workflows
Version 1.1 (Legacy)
When should I use this version?
Use this version if:
You already have an existing 1.0 or 1.1 connection and are not able to upgrade to 2.0
Request schema
{
"metadata": {
"schemaVersion": "1.1",
"platformVersion": "1.1",
"documentBundleEndpointVersion": "1.1"
},
"despatchPackage": {
"despatchPackageId": 1,
"despatch": {
"despatchNumber": "DES100",
"carrier": {
"name": "Royal Mail",
"reference": "RM"
},
"serviceType": {
"name": "Royal Mail Next Day",
"code": "RM24",
"outboundReference": ""
},
"loadReference": "",
"salesOrder": {
"salesOrderNumber": "SO100",
"customer": {
"name": "Matt Thomson",
"reference": "123456789",
"firstName": "Matt",
"lastName": "Thomson",
"phone": "",
"mobile": "",
"email": "matt.thomson@peoplevox.com",
"creditLimit": "",
"paymentTerm": ""
},
"customerPurchaseOrderReferenceNumber": "",
"shippingAddress": {
"line1": "119",
"line2": "Marylebone Road",
"townCity": "London",
"region": "",
"postCode": "NW1 5PU",
"countryName": "United Kingdom",
"countryCode": "UK"
},
"invoiceAddress": {
"line1": "119",
"line2": "Marylebone Road",
"townCity": "London",
"region": "",
"postCode": "NW1 5PU",
"countryName": "United Kingdom",
"countryCode": "UK"
},
"requestedDeliveryDate": "01/01/2018 00:00:00",
"shippingCost": "0.00",
"email": "matt.thomson@peoplevox.com",
"contactName": "Matt Thomson",
"paymentMethod": "Cash",
"totalSale": "0.00",
"discount": "0.00",
"taxPaid": "0.00",
"createdDate": "",
"channelName": "My website",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"site": "PrimarySite",
"currency": "GBP",
"termsOfTrade": "DDP",
"customsRegistrationNumber": "EoriNumbersOrSimilar",
"iossNumber": "YourIossNumber",
"deliveryNotes": "Leave at door, for example"
"contentsType": "Merchandise, for example",
"status": "Despatched",
"totalPickedItems": 1,
"totalDespatchedItems": 1,
}
},
"weight": "0.00",
"height": "0.00",
"width": "0.00",
"depth": "0.00",
"packageType": {
"name": "",
"barcode": ""
},
"packageNumber": 1,
"carrier": {
"name": "Royal Mail",
"reference": "RM"
},
"serviceType": {
"name": "Royal Mail Next Day",
"code": "RM24",
"outboundReference": ""
},
"despatchItems": [
{
"itemType": {
"itemCode": "ItemA",
"name": "Item A",
"barcode": "ITEMA001",
"description": "This is a lovely widget",
"itemGroup": "Widgets",
"unitOfMeasure": {
"name": "Unit",
"symbol": "EA"
},
"defaultSupplierPartNumber": "MYWIDGETA",
"buyPrice": "0.00",
"wholesalePrice": "0.00",
"retailPrice": "0.00",
"weight": "1.00",
"weightMeasure": "kg",
"height": "1.00",
"width": "1.00",
"depth": "1.00",
"dimensionMeasure": "cm",
"tags": "",
"taxCode": "",
"attribute1": "",
"attribute2": "",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"attribute6": "",
"attribute7": "",
"attribute8": "",
"attribute9": "",
"attribute10": "",
"attribute11": "",
"attribute12": "",
"attribute13": "",
"attribute14": "",
"attribute15": "",
"salePrice": "10.00",
"salesOrderItemAttribute1": "",
"salesOrderItemAttribute2": "",
"salesOrderItemAttribute3": "",
"salesOrderItemLine": "1",
"hsCode": "6101",
"countryOfOrigin": "GBR",
"dryIce": false,
"medicalDryIce": false,
"alcohol": false,
"hazardous": false
},
"quantity": 1,
"container": {
"barcode": "",
"reference": ""
}
}
]
},
"oldPrintRequests": [
{
"printRequestId": 1,
"documentReference": "Carrier label"
},
{
"printRequestId": 2,
"documentReference": "Customs documentation"
},
{
"printRequestId": 3,
"documentReference": "Returns label"
}
]
}Change log
schemaVersion 1.0 -> 1.1:
Added "salePrice", "salesOrderItemAttribute1", "salesOrderItemAttribute2", "salesOrderItemAttribute3", and "salesOrderItemLine" to the despatchItems.ItemType collection.
Added "hsCode", "countryOfOrigin", "dryIce", "medicalDryIce", "alcohol", and "hazardous" to the despatchItems.ItemType collection
Added "currency", "termsOfTrade", "customsRegistrationNumber", and "iossNumber" to the salesOrder entity
platformVersion 1.0 -> 1.1:
Added the ability for the documentBundleEndpoint to respond with a service type selection, which will be saved against the package in Peoplevox. See the Responses section for more info.
documentBundleEndpointVersion 1.0 -> 1.1:
Added the ability for the documentBundleEndpoint to respond with a service type selection, which will be saved against the package in Peoplevox. See the Responses section for more info.