Batch Container Label API

Note

Draft content. This operation is coming soon. This page is a draft.

HTTP Request

POST /v1/container-manifest/Batch?carrier=PBI

Summary

This operation prints a batch of container labels for containerized CBDS parcels that use International Inbound shipping. The API returns the container labels in a single PDF file. Each page in the PDF is a different container label.

Before issuing this API call, you must print the parcel labels using the CBDS International Inbound API.

Note: This operation is specific to CBDS. To create a container label for a different carrier, see this operation.

Prerequisite

To use this API, a merchant must contact Pitney Bowes for enablement. The merchant should contact either ClientSupportTechServices@pb.com, or ShippingAPIBusinessDevelopment@pb.com, or the implementation manager.

Considerations

  1. The operation prints container labels for parcel shipments created with the CBDS International Inbound API.

  2. The operation returns a PDF with a separate page for each container label.

  3. This operation returns a batch ID for the labels in the batchContainerManifestId field.

  4. If you need to reprint the container labels, use the Reprint Batch Container Labels API. When you reprint, you must pass the batchContainerManifestId in the reprint request.

  5. If the label fails and you need to retry it, reissue this Batch Container Label API but use a new Transaction ID (X-PB-TransactionId).

Request URLs

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/container-manifest/Batch?carrier=PBI
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/container-manifest/Batch?carrier=PBI

Query Parameter

Name

Description

carrier

Required. The carrier for the parcels in the container. Valid value: PBI

PBI is the Cross-Border Delivery Service (CBDS).

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 / Response Elements

Name

Data Type

Description

containers

Array[Container Object]

Required. The containers to be shipped. The containers array contains a different container object for each container to be shipped.

parameters

Array[Object]

Required. Specifies the Pitney Bowes hub that will receive the containers.

parameters.name

String

Required. Enter the following: CARRIER_FACILITY_ID

parameters.value

String

Required. The Pitney Bowes hub that will receive the containers. Possible values:

  • US_GLOBAL_ILA

  • US_GLOBAL_NJA

  • US_GLOBAL_WAA

documents

Array[Object]

Defines properties for the returned container labels. This object is optional. The Batch Container Label API uses one set of properties for all container labels. If you leave this object out of the request, the API applies the default values.

Note that if you choose to include the object, you must include all the object’s fields (except for the RESPONSE-only field) or the request will fail.

documents.type

String

The type of document to be returned. Valid value: CONTAINER_LABEL

documents.size

String

The size of each container label. Valid value: DOC_4X6

documents.contentType

String

Indicates that the API returns the document as a Base64-encoded string that can be converted to a PDF. To convert, use a tool that converts Base64 to the application/pdf MIME type. Valid value: BASE64

documents.fileFormat

String

Indicates the file format for the printable label. Valid value: PDF

documents.contents

String

RESPONSE ONLY. The Base64-encoded string that converts to a PDF. The PDF contains the container labels. Each label is a different page in the PDF. To convert, use a tool that converts Base64 to the application/pdf MIME type.

references

Array[Object]

Defines reference fields. Each object in the array specifies a different reference and value. For available references, See References Array Reference Types.

references.name

String

The reference.

references.value

String

The reference’s value.

batchContainerManifestId

String

RESPONSE ONLY. The unique shipment number generated by Pitney Bowes. This number appears as barcode and number on each container label returned in the PDF. If you need to reprint the container labels, you must pass the batchContainerManifestId in the reprint request.

Container Object

Name

Data Type

Description

clientContainerId

String

Required. The client number for the container.

Maximum length: 50 characters

containerType

String

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

  • Airhaul

  • Box

  • Gaylord

submissionDate

String

The API includes all parcels that have been manifested but not shipped or containerized through the specified date. Specify the 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. For example:

"2022-08-28T18:59:59.000Z"

tareWeight

Object

The weight of the container when empty, before the parcels are added.

tareWeight.Weight

Big Decimal

The weight of the empty container. If you enter a value for this field, you must also enter a value for tareWeight.unitOfMeasurement.

tareWeight.unitOfMeasurement

String

The unit of measure for the tare weight. Valid values are:

  • LB: pounds

  • KG: kilograms

  • OZ: ounces

dimension

Dimension Object

The container’s dimensions.

totalParcelWeight

Object

The total scaled weight of all the parcels in the container, without the container weight (tare weight).

totalParcelWeight.Weight

Big Decimal

The totals scaled weight of all the parcels. Do not include the container weight.

totalParcelWeight.unitOfMeasurement

String

The unit of measure for the total weight. Valid values are:

  • LB: pounds

  • KG: kilograms

parcelTrackingNumbers

Array[Strings]

Required. The tracking numbers of the parcels on this container, entered as Strings separated by commas.

References Array Reference Types

The references array in the Batch Container Label API takes the reference types described here. The references array is optional in the request. Each reference type is optional in the array.

Name

Description

CLIENT_REFERENCE_NUMBER

Unique client shipment number.

CLIENT_GROUND_REFERENCE_NUMBER

Unique client ground reference number (truck number).

CLIENT_AIR_REFERENCE_NUMBER

Unique client air reference number (airline number).

Sample Request

curl -X POST ".../v1/container-manifest/batch?carrier=PBI" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: 45672345" \
-d '
{
    "containers": [ {
        "clientContainerId": "CLIENT_CA_20220828_01",
        "containerType": "BOX",
        "tareWeight": {
            "weight": 48.0,
            "unitOfMeasurement": "LB"
        },
        "dimension": {
            "length": 48.0,
            "width": 36.0,
            "height": 24.5,
            "unitOfMeasurement": "IN"
        },
        "totalParcelWeight": {
            "weight": 48.0,
            "unitOfMeasurement": "LB"
        },
        "parcelTrackingNumbers": [
            "UPBEE001699999999A16",
            "UPBEE001699999999A12",
            "UPBEE001699999999917",
            "UPBEE001699999999918",
            "UPBEE001699999999915"
        ]
    },
    ...
    ],
    "parameters": [ {
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    } ],
    "documents": [ {
        "type": "CONTAINER_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "BASE64"
    } ],
    "references": [ {
        "name": "CLIENT_REFERENCE_NUMBER",
        "value": "MerchantOrder-1195"
    },{
        "name": "CLIENT_GROUND_REFERENCE_NUMBER",
        "value": "MerchantOrder-1195"
    },{
        "name": "CLIENT_AIR_REFERENCE_NUMBER",
        "value": "MerchantOrder-1195"
    } ]
}'

Sample Response

Sample Response
{
    "containers": [ {
        "clientContainerId": "CLIENT_CA_20220828_01",
        "containerType": "BOX",
        "tareWeight": {
            "weight": 48.0,
            "unitOfMeasurement": "LB"
        },
        "dimension": {
            "length": 48.0,
            "width": 36.0,
            "height": 24.5,
            "unitOfMeasurement": "IN"
        },
        "totalParcelWeight": {
            "weight": 48.0,
            "unitOfMeasurement": "LB"
        },
        "parcelTrackingNumbers": [
            "UPBEE001699999999A16",
            "UPBEE001699999999A12",
            "UPBEE001699999999917",
            "UPBEE001699999999918",
            "UPBEE001699999999915"
        ]
    },
    ...
    ],
    "parameters": [ {
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    } ],
    "documents": [ {
        "type": "CONTAINER_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "BASE64",
        "contents": "https://.../9de8b17ad4149f2ad1a5df38f054a9b.pdf"
    } ],
    "references": [ {
        "name": "CLIENT_REFERENCE_NUMBER",
        "value": "MerchantOrder-1195"
    },{
        "name": "CLIENT_GROUND_REFERENCE_NUMBER",
        "value": "MerchantOrder-1195"
    },{
        "name": "CLIENT_AIR_REFERENCE_NUMBER",
        "value": "MerchantOrder-1195"
    } ],
    "batchContainerManifestId": "<Id>"
}

Error Codes

The API uses the following error codes:

Error Code

Error Message

Solution

1009999

A system error occurred, try again later. If the error persists, please contact the service provider.

Contact Us

1110001

Duplicate parceltrackingnumber in request.

1110011

Invalid parcelTrackingNumber in request.

1310002

Invalid or missing value

1310005

Invalid parcelTrackingNumber-CarrierFacilityId in request.

1310006

Voided parcelTrackingNumber in request.

1310007

Document Generation Error. Please use Reprint API to generate the artifacts.

For a list of all error codes returned by the Ecommerce APIs, please see Error Codes.