Batch Container Manifest API

Note

This API operation is Coming Soon.

Note

This page contains draft content.

HTTP Request

POST /v1/container-manifest/batch?carrier={id}

Summary

This operation prints Pitney Bowes container labels for a batch of containerized parcels being shipped to a Pitney Bowes facility.

Through the API, the merchant sends Pitney Bowes a list of all the containers and all the corresponding tracking numbers in each container. The API returns labels for each container. The API returns the labels in a single PDF. Each page in the PDF is a different container label. The merchant uses the labels to ship the containers to a Pitney Bowes facility.

Considerations

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

  2. This operation returns a Batch Container Manifest ID (batchContainerManifestId).

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

  4. If the label fails and you need to retry it, reissue the Batch Container Manifest 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={id}
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/container-manifest/batch?carrier={id}

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

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

The references array in the Batch Container Manifest API takes the references described here.

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"
        ]
    },
    {
        "clientContainerId": "CLIENT_CA_20220828_02",
        ...
    },
    {
        "clientContainerId": "CLIENT_CA_20220828_03",
        ...
    },
    {
        "clientContainerId": "CLIENT_CA_20220828_04",
        ...
    },
    ...
    ],
    "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
{



}

Error Codes