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¶

The operation returns a PDF with a separate page for each container label.
This operation returns a Batch Container Manifest ID (batchContainerManifestId).
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.
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¶

{

}