Print a Container Label for Shipment to a PB Standard Facility¶
HTTP Request¶
POST /v1/container-manifest
Summary¶
This operation prints a Pitney Bowes container label for shipping containerized PB Standard parcels to a Pitney Bowes facility. Upon arrival at the facility, the container label is scanned to confirm receipt.
Note
This operation applies to PB Standard containers. For CBDS containers, see Master Carton and Batch Labels.
Considerations¶
The operation returns a container label (see the example below) and a Pitney Bowes Container ID.
You can optionally specify which parcels are included in the container by doing one of the following. You cannot do both in the same API call:
To automatically pull in all parcels that have been manifested by a certain date but that have not yet been shipped, use the
submissionDate
field.To explicitly specify a list of parcels, use the
parcelTrackingNumbers
array.
Important You cannot include both fields in the request. If you do you will receive an error.
The container’s parcels use the carrier listed in the API call’s
carrier
field. Currently, parcels must use PB Standard.When using the
submissionDate
field, wait a half hour between calling the Manifest API and calling the Container Label API in order to ensure that manifesting has completed and the container label will include all intended transactions.The operation can optionally return just the barcode. To do so, set the
barcodeOnly
field totrue
.The container label is returned either as raw ZPL or as a Base64-encoded PDF, PNG, or JPEG.
For a Base64-encoded label, you must convert the Base64 to one of the following MIME types, depending on the file format:
For this file format:
Convert the label to this MIME type:
PDF
application/pdf
PNG
image/png
JPEG
image/jpeg
If a shipper needs to make changes to a container label after printing it, the shipper can open the original request, enter a new unique value for the
X-PB-TransactionId
, make the changes, and reissue the request. The API will return a new label with a new Pitney Bowes Container ID (pbContainerId
). The original label can be discarded.For example, if a shipper needs to add tracking numbers to the
parcelTrackingNumbers
array, the shipper can add the tracking numbers and reissue the request with a newX-PB-TransactionId
value. The API will return a new container label.Shippers can also generate container labels through the Merchant Portal.
Request URLs¶
Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/container-manifest
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/container-manifest
Request Headers¶
Name |
Description |
---|---|
Authorization |
Required. OAuth token generated using the Generate an OAuth Token API. |
Content-Type |
Required. The media type of the request entity. Set this to |
X-PB-TransactionId |
Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( Important: Ensure this is a unique ID. |
Request Elements¶
Parameters¶
The parameters
array in the Create a Container Label request can take the parameters described here.
Name |
Description |
---|---|
CARRIER_FACILITY_ID |
Required.The Pitney Bowes facility at which the container will be processed. Enter the numeric facility code. If testing the Container API on Sandbox, set this to For a list of facilities, see https://www.docs.pitneybowes.com/document/standard-delivery-product-service-guide#appendix-a. |
CARRIER_GATEWAY_FACILITY_ID |
Required.The Pitney Bowes facility at which the container will enter the PB network. Enter the numeric facility code. If testing the Container API on Sandbox, set this to For a list of facilities, see https://www.docs.pitneybowes.com/document/standard-delivery-product-service-guide#appendix-a. |
CLIENT_CONTAINER_ID |
The client’s ID for the container. Note that the CLIENT_CONTAINER_ID is not the same as the Pitney Bowes Container ID returned in the response. |
CLIENT_ID |
Required. The carrier-specific client ID. If testing the Container API on Sandbox, set this to |
CURRENT_CONTAINER |
The current container number. If you use this parameter, you should also use the TOTAL_CONTAINER_COUNT parameter. The label displays the parameters as follows: Container <CURRENT_CONTAINER> of <TOTAL_CONTAINER_COUNT> For example: Container 8 of 10 |
ESTIMATED_ARRIVAL_DATE |
The estimated date the container will arrive, specified in the following format: |
PACKAGE_COUNT |
Specifies the number of parcels in the container. Use this parameter only if you leave out both the |
PRINT_CUSTOM_MESSAGE_1 |
The handling instructions. This will appear on the label under INSTRUCTIONS, as shown in the sample label below. |
SHIP_DATE |
Required. The date the container will be shipped, specified in the following format: |
SHIPMENT_REFERENCE_NUMBER |
The Bill of Lading or other shipment reference number associated with the container. |
TOTAL_CONTAINER_COUNT |
The total number of containers in the shipment. If you use this parameter, you should also use the CURRENT_CONTAINER parameter. |
Response Elements¶
Name |
Data Type |
Description |
||||||||
---|---|---|---|---|---|---|---|---|---|---|
data |
Object |
The container label and the Pitney Bowes Container ID. |
||||||||
data.pbContainerId |
String |
The unique Pitney Bowes Container ID assigned to the container. |
||||||||
data.labelData |
String |
The label, returned either as raw ZPL or as a Base64-encoded string. If a Base64-encoded string, convert the string to one of the following MIME types, depending on the value passed in
|
Sample Requests¶
See the following examples:
Sample Request for a Container Label¶
The following request uses the parcelTrackingNumbers
array to specify which parcels are included in the container.
curl -X POST ".../v1/container-manifest" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: abc12345678" \
-d '
{
"carrier": "PBCS",
"containerType": "Carton",
"parcelTrackingNumbers": [
"4204514092748000000000000000010000",
"4204514092612000000000000000002000",
"4204514092612000000000000000300000",
"4204514092748000000000000000000400",
...
],
"documents": [ {
"fileFormat": "PDF",
"size": "DOC_4X4",
"resolution": "DPI_203"
} ],
"parameters": [ {
"name": "CARRIER_FACILITY_ID",
"value": "1585"
},{
"name": "CARRIER_GATEWAY_FACILITY_ID",
"value": "1585"
},{
"name": "CLIENT_CONTAINER_ID",
"value": "AB12345678"
},{
"name": "CLIENT_ID",
"value": "NGST"
},{
"name": "CURRENT_CONTAINER",
"value": "4"
},{
"name": "ESTIMATED_ARRIVAL_DATE",
"value": "2021-01-24"
},{
"name": "PRINT_CUSTOM_MESSAGE_1",
"value": "Bounded Printed Matter, Handle Separately!"
},{
"name": "SHIP_DATE",
"value": "2021-01-22"
},{
"name": "SHIPMENT_REFERENCE_NUMBER",
"value": "CD12345678"
},{
"name": "TOTAL_CONTAINER_COUNT",
"value": "7"
} ]
}'
{
"data": {
"pbContainerId": "5e9030d0ca7d01031c6967a0",
"labelData": "JVBERi0xLjQKJeLjz9MKNCAwIG9iago8PC9EZWNvZGVQYXJtczw8L0sgLTEvQ29sdW1ucyAyMi9Sb3dzIDIyP5FH..."
}
}
Sample Container Label¶
Sample Request for a Container Barcode¶
The following example sets the barcodeOnly
to true
so that the API returns only the barcode. The request uses the submissionDate
field to specify which parcels are included in the container.
curl -X POST ".../v1/container-manifest" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: abc12345679" \
-d '
{
"carrier": "PBCS",
"containerType": "Carton",
"submissionDate": "2021-02-16T23:59:59.000Z",
"documents": [ {
"fileFormat": "ZPL",
"size": "DOC_4X4",
"resolution": "DPI_203"
} ],
"barcodeOnly": true,
"parameters": [ {
"name": "CARRIER_FACILITY_ID",
"value": "1585"
},{
"name": "CARRIER_GATEWAY_FACILITY_ID",
"value": "1585"
},{
"name": "CLIENT_CONTAINER_ID",
"value": "AB12345679"
},{
"name": "CLIENT_ID",
"value": "NGST"
},{
"name": "CURRENT_CONTAINER",
"value": "44"
},{
"name": "ESTIMATED_ARRIVAL_DATE",
"value": "2021-02-18"
},{
"name": "SHIP_DATE",
"value": "2021-02-18"
},{
"name": "SHIPMENT_REFERENCE_NUMBER",
"value": "CD12345679"
} ]
}'
{
"data": {
"pbContainerId": "6038ff9f0988c10007b50a22",
"labelData": "^XA^FO0,0^BXN,12,200^FH^FDt:container|i:603903db737e50000725fe92^FS^XZ"
}
}
Sample Container Barcode¶
Error Codes¶
For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.