Print Batch Container Labels for CBDS Inbound¶

HTTP Request¶

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

Summary¶

This operation prints a batch of container labels for shipping containerized parcels that use CBDS International Inbound Delivery. This operation is used with the Drop-Off to U.S. Hub delivery solution.

The container labels ship to a CBDS Hub. The API returns the container labels as a single PDF file with a different container label on each page. The first page of the PDF includes an MAWB ID in addition to a container label.

Before printing container labels with this API, you must print the shipping labels for the parcels to be containerized. Print the shipping labels using the Create CBDS International Inbound Shipment API.

Note

This operation applies to CBDS Inbound containers. For CBDS Outbound see Master Carton, and for PB Standard see Container Label.

Prerequisite¶

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

Considerations¶

In addition to returning the container labels, the API response returns a batch ID that identifies the batch of container labels. The response returns the ID in the batchContainerManifestId field. The ID also appears on each container label.
If this API request fails and you need to reissue the request, you must use a new Transaction ID (X-PB-TransactionId) when you reissue the request. Do not use the same Transaction ID.
If you need to reprint the container labels, use the Reprint Batch Container Labels API and pass the batchContainerManifestId ID from the original request. Do not reprint the labels if the original request failed. Instead reissue the request with a new Transaction ID (X-PB-TransactionId), as mentioned above.
Do not use carriage return (CR) or line feed (LF) characters within Strings in the API request.

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 Elements¶

Name	Data Type	Description
containers	Array[Container Object]	Required. The containers to be shipped. The array contains an object for each container to be shipped.
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 or the request will fail.
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.size	String	The size of each container label. Valid value: `DOC_4X6`
documents.type	String	The type of document to be returned. Valid value: `CONTAINER_LABEL`
references	Array[Object]	Defines reference fields. Each object in the array specifies a different reference and value. For available references, See Reference Types.
references.name	String	The reference.
references.value	String	The reference’s value.
parameters	Array[Object]	Required. Contains a key-value pair that specifies the CBDS Hub that receives 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`

Response Elements¶

Name	Data Type	Description
containers	Array[Container Object]	The containers to be shipped. The array contains an object for each container to be shipped.
documents	Array[Object]	The returned container labels.
documents.contentType	String	Returns the following to indicate the label is a Base64-encoded string that must be converted to a PDF: `BASE64` To convert the string, use a tool that converts Base64 to the application/pdf MIME type.
documents.fileFormat	String	Returns the following to indicate the file format for the printable label: `PDF`
documents.size	String	Returns the following to indicate label size is 4 x 6: `DOC_4X6`
documents.contents	String	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.
documents.type	String	Returns the following to indicate the label is a container label: `CONTAINER_LABEL`
references	Array[Object]	Contains key-value pairs that specify shipper reference values. Each object in the array has a `name` field set to the reference type and a `value` field set to the reference value. See Reference Types.
parameters	Array[Object]	Contains a key-value pair that specifies the CBDS Hub that receives the containers.
parameters.name	String	Returns `CARRIER_FACILITY_ID` to indicated the parameter is a facility ID.
parameters.value	String	The CBDS Hub that receives the containers. Possible values: `US_GLOBAL_ILA`: Chicago `US_GLOBAL_NJA`: New Jersey `US_GLOBAL_WAA`: Washington state
batchContainerManifestId	String	The unique shipment number generated by Pitney Bowes. This number appears as barcode and number on each container label returned in the PDF.

Container Object¶

Name	Data Type	Description
clientContainerId	String	Required. The number for the container generated by the shipper. Maximum length: 50 characters
containerType	String	The type of container used to transport the parcels. Possible values: `AIRHAUL` `BOX` `GAYLORD`
tareWeight	Object	The weight of the container 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 (tare weight).
totalParcelWeight.unitOfMeasurement	String	The unit of measure for the total scaled weight. Valid values: `LB`: pounds `KG`: kilograms
parcelTrackingNumbers	Array[Strings]	Required. The tracking numbers of the parcels on this container. Enter the tracking numbers as Strings separated by commas.

Reference Types¶

The references array in the Batch Container Label API takes the reference types described here. Enter the reference type in the references.name field and its value in the references.value field. Each reference type is optional.

Name	Description
`CLIENT_REFERENCE_NUMBER`	A unique shipment number generated by the shipper.
`CLIENT_GROUND_REFERENCE_NUMBER`	A unique ground reference number (truck number) generated by the shipper.
`CLIENT_AIR_REFERENCE_NUMBER`	A unique air reference number (airline number) generated by the shipper.

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": "c1112136513-PC1",
        "containerType": "BOX",
        "tareWeight": {
            "unitOfMeasurement": "LB",
            "weight": 8.10
        },
        "dimension": {
            "length": 48.0,
            "height": 24.5,
            "width": 36.0,
            "unitOfMeasurement": "IN"
        },
        "totalParcelWeight": {
            "unitOfMeasurement": "LB",
            "weight": 1.0
        },
        "parcelTrackingNumbers": [
            "UPBEE001000000000A16",
            "UPBEE001000000000A12",
            "UPBEE001000000000917",
            "UPBEE001000000000918",
            "UPBEE001000000000915"
        ]
    },
    ...
    ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "PDF",
        "size": "DOC_4X6",
        "type": "CONTAINER_LABEL"
    } ],
    "references": [ {
        "name": "CLIENT_REFERENCE_NUMBER",
        "value": "1234"
    } ],
    "parameters": [ {
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    } ]
}'

Sample Response¶

{
    "containers": [ {
        "clientContainerId": "c1112136513-PC1",
        "containerType": "BOX",
        "tareWeight": {
            "unitOfMeasurement": "LB",
            "weight": 8.10
        },
        "dimension": {
            "length": 48.0,
            "height": 24.5,
            "width": 36.0,
            "unitOfMeasurement": "IN"
        },
        "totalParcelWeight": {
            "unitOfMeasurement": "LB",
            "weight": 1.0
        },
        "parcelTrackingNumbers": [
            "UPBEE001000000000A16",
            "UPBEE001000000000A12",
            "UPBEE001000000000917",
            "UPBEE001000000000918",
            "UPBEE001000000000915"
        ]
    },
    ...
    ],
    "documents": [ {
        "contentType": "BASE64",
        "fileFormat": "PDF",
        "size": "DOC_4X6",
        "contents": "JVBERi0xLjMNCjE3umAG ...",
        "type": "CONTAINER_LABEL"
    } ],
    "references": [ {
        "name": "CLIENT_REFERENCE_NUMBER",
        "value": "1234"
    } ],
    "parameters": [ {
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    } ],
    "batchContainerManifestId": "OBMEL123456789"
}

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.