Print a Container Label for Shipment to a PB Facility¶

HTTP Request¶

POST /v1/container-manifest

Summary¶

This operation prints a Pitney Bowes container label for shipping containerized PB 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 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 to true.
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 new X-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 application/json.

X-PB-TransactionId

Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens (-), and underscores (_).

Important: Ensure this is a unique ID.

Request Elements¶

Name	Data Type	Description
carrier	String	Required. The parcels in the container use the carrier listed here. Possible value: `PBCS` (PB Standard)
containerType	String	The type of container used to transport the parcels. Possible values: `Carton` `Pallet` `Gaylord` `LicensePlate` `Truck`
submissionDate	String	Specifies a date that determines which parcels are included in the container. When a date is specified, the API includes all parcels that have been manifested through that date but that have not yet been shipped or containerized. This field lets you add parcels to the container without your having to list out each parcel. Specify the submission date in your time zone and use the ISO 8601 extended format including your time zone offset: YYYY-MM-DDThh:mm:ss.sss+-HH:mm The value must include both date and time and must indicate timezone offset. The following is an example value for this field: `"2021-02-01T18:59:59.000+07:00"` Important If you use this field, you cannot use the `parcelTrackingNumbers` array. If you do you will receive an error.
parcelTrackingNumbers	Array[String]	Lists all the parcels to be included in the container. The array identifies parcels by their tracking numbers. To add parcels without listing them out, use the `submissionDate` field instead. Important: You cannot use the `submissionDate` field and `parcelTrackingNumbers` array in the same call. If you do, you will receive an error.
documents	Array[Object]	Required. Defines the container label.
documents.fileFormat	String	The file format for the printable label. Possible values: `JPEG`: Returns the label as a Base64-encoded JPEG. To convert, use a tool that converts Base64 to the image/jpeg MIME type. `PDF`: Returns the label as a Base64-encoded PDF. To convert, use a tool that converts Base64 to the application/pdf MIME type. `PNG`: Returns the label as a Base64-encoded PNG. To convert, use a tool that converts Base64 to the image/png MIME type. `ZPL`: Returns the label as raw ZPL. By default, the APIs print ZPL labels using the Unicode character set. If you have an older printer that does not support Unicode, see this Troubleshooting topic.
documents.size	String	The label size. Possible values: `DOC_4X4` `DOC_6X4` Note: Clients are required to print 2 copies of labels and affix them on different sides of each container. This helps to increase scan speeds at Pitney Bowes facilities.
documents.resolution	String	The label’s dots per inch (DPI). By default, the resolution is 203 DPI. Possible values: `DPI_203` (Default) `DPI_300`
barcodeOnly	Boolean	If set to `true`, the API prints only the barcode and no other label information. The default value is `false`. The following is an example of the printed label when `barcodeOnly` is set to `true`:
parameters	Array[Object]	Required. Defines reference fields and shipment options. Each object in the array specifies a different parameter and value. For available parameters, See Parameters.
parameters.name	String	The parameter.
parameters.value	String	The parameter’s value.

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 `1585`. 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 `1585`. 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 `NGST`.
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: `YYYY-MM-DD`
PACKAGE_COUNT	Specifies the number of parcels in the container. Use this parameter only if you leave out both the `submissionDate` field and the `parcelTrackingNumbers` array. If you specify either of those fields, this parameter is ignored.
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: `YYYY-MM-DD`
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 documents.fileFormat in the request:

File format:	Convert to this MIME type:
PDF	application/pdf
PNG	image/png
JPEG	image/jpeg

Sample Requests¶

See the following examples:

Sample Request for a Container Label
Error Codes

Sample Request for a Container Label¶

The following request uses the parcelTrackingNumbers array to specify which parcels are included in the container.

Sample Request for a Container Label¶

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"
    } ]
}'

Sample Response¶

{
    "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.

Sample Request for a Container Barcode¶

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"
    } ]
}'

Sample Response¶

{
    "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.

For this file format:	Convert the label to this MIME type:
PDF	application/pdf
PNG	image/png
JPEG	image/jpeg