Create a Container Label

HTTP Request

POST /v1/container-manifest

Summary

This operation prints a Pitney Bowes container label for the shipment of containerized parcels from the client location to a Pitney Bowes facility. Upon arrival at the Pitney Bowes facility, the container label is scanned to confirm receipt.

Considerations

  1. The operation returns a container label and a Pitney Bowes container ID (pbContainerId). For a sample label, see the example at the end of this page.

  2. You can optionally specify which parcels are included in the container:

    • 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.

    Note: You cannot include both fields in the request. If you do you will receive an error.

  3. The container’s parcels use the carrier listed in the API call’s carrier field. Currently, parcels must use PB Standard.

  4. When using the submissionDate option, 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.

  5. The operation can optionally return just the barcode. To do so, set the barcodeOnly field to true.

  6. The container label is returned either as raw ZPL or as a Base64-encoded PDF. If you request the label as a Base64-encoded PDF, you must convert the Base64 to the application/pdf MIME type.

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

  8. Shippers can also generate container labels through the Merchant Portal.

Request URLs

Sandbox: https://api-sandbox.pitneybowes.com/shippingservices/v1/container-manifest
Production: https://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.

Important: You must 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:

  • Newgistics (PB Standard)
containerType String

The type of container used to transport the parcels. Possible values:

  • Carton
  • Pallet
  • Gaylord
  • LicensePlate
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 UTC/GMT and use the ISO 8601 extended format:

YYYY-MM-DDThh:mm:ss.sssZ

The value must include both date and time and must end with Z to indicate the zero offset. The following is an example value for this field: "2021-02-01T18:59:59.000Z"

If you use this field, you cannot use the parcelTrackingNumbers field. 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.

Note: To add parcels without listing them out, use the submissionDate field instead.

If you use this field, you cannot use the submissionDate field. If you do you will receive an error.

documents Array[Object] Required. Defines the container label.
    fileFormat String

The file format for the printable label. Possible values:

  • PDF: Returns the label as a Base64-encoded PDF that must be converted to the application/pdf MIME type.

    To convert, use a tool that converts Base64 to the application/pdf 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.

    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.

    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:

Barcode-only Container Label
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.
    name String The parameter.
    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. For a list of facilities, see PB Standard Facilities.
CARRIER_GATEWAY_FACILITY_ID Required.The Pitney Bowes facility at which the container will enter the PB network. Enter the numeric facility code. For a list of facilities, see PB Standard Facilities.
CLIENT_CONTAINER_ID The client’s container ID or container number.
CLIENT_ID Required. The carrier-specific client or merchant ID. If testing in the Sandbox environment, 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.”
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 label and label ID.
    pbContainerId String The unique Pitney Bowes identifier for the label.
    labelData String The label, returned either as raw ZPL or as a Base64-encoded string that must be be decoded as a PDF using a tool that converts Base64 to the application/pdf MIME type.

Sample Request for a Container Label

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": "Newgistics",
    "containerType": "Carton",
    "submissionDate": "2021-01-22T20:30:00.000Z",
    "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 Container Label

Sample Request for a Container Barcode

The following example sets the barcodeOnly to true so that the API returns only the barcode.

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": "Newgistics",
    "containerType": "Carton",
    "submissionDate": "2021-01-22T20:30:00.000Z",
    "parcelTrackingNumbers": [
        "4204514092748000000000000000010000",
        "4204514092612000000000000000002000",
        "4204514092612000000000000000300000",
        "4204514092748000000000000000000400",
        ...
    ],
    "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-19"
    },{
        "name": "SHIP_DATE",
        "value": "2021-02-19"
    },{
        "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

Barcode-only Container Label


Error Codes

For a list of all PB Shipping APIs error codes, please see Error Codes.