Create a Master Carton for CBDS Outbound (U.S. or Canada) or CBDS Canada Domestic¶

HTTP Request¶

POST /v2/container-manifest

Summary¶

This operation prints the shipping label and container label for a CBDS master carton. The API also returns a tracking number and shipment ID. A master carton is a container used to ship CBDS Outbound parcels to a CBDS Hub. At the hub, CBDS processes the parcels and ships them to their international destinations. You can create master cartons for shipments originating in the U.S. or Canada.

The API prints two labels. The shipper must affix both labels to the same side of the master carton. The API prints the following:

A shipping label that uses the postal service to ship the master carton to the CBDS hub. The shipper can use the label or optionally drop off the master carton directly to the hub. See the example shipping label at the end of this page.
A container label that reads “Master Carton” to identify the container as such. See the example container label at the end of this page.

Note

Master cartons ship CBDS Outbound parcels. For containers for CBDS Inbound, see Batch Labels. For PB Standard containers, see Container Label.

Prerequisites¶

To ship with CBDS Master Carton, a merchant must first be enabled and onboarded. To request enablement, contact Pitney Bowes at either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com, or contact the merchant’s Pitney Bowes implementation manager. During enablement, the merchant sets up one or more delivery solutions.

Note

To use Master Carton, the new DELIVERY_SOLUTION shipment option must also be used.

Considerations¶

The master carton can contain up to 250 outbound parcels.
Master cartons use the PB Master Carton Domestic Standard (PBMDS) service.
Master cartons use the package (PKG) parcel type.
Do not use carriage return (CR) or line feed (LF) characters within Strings in the API request.
The shipping label and container label are available for 24 hours after the request.
The shipper must affix the shipping label and container label to the same side of the master carton.
The pickup and first mile parcels cannot be containerized. If you containerize, you will receive an error.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v2/container-manifest
Production: https://shipping-api.pitneybowes.com/shippingservices/v2/container-manifest

Query Parameter¶

The query parameter is optional.

Name	Description
includeDeliveryCommitment	If you include this parameter and set it to `true`, the API returns the estimated transit time for the master carton. The API returns transit time as the number of days.

Request Headers¶

Name

Description

Authorization

Required. The 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 this 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
containerType	String	Required. Set this to: `MasterCarton`
fromAddress	Address Object	The master carton’s origin address.
weight	Object	The weight of the container when empty, before parcels are added.
weight.weight	Big Decimal	The weight of the empty container. If you enter a value for this field, you must also enter a value for `weight.unitOfMeasurement`.
weight.unitOfMeasurement	String	The unit of measure for `weight.weight`. Valid values: `LB`: pounds `KG`: kilograms `OZ`: ounces
dimension	Dimension Object	The container’s dimensions.
rates	Array[Object]	Required. The carrier, service, and parcel type. The array contains one object.
rates.carrier	String	Set this to: `PBI`
rates.serviceId	String	Set to this to the PB Master Carton Domestic Standard service: `PBMDS`
rates.parcelType	String	Set this to the package parcel type: `PKG`
documents	Array[Object]	Required. This array takes one object. The object defines the first-mile shipping label. Note that in the response the array will return two objects, one for the shipping label and one for the container label.
documents.type	String	Enter the following to indicate the label is a first-mile shipping label: `SHIPPING_LABEL`
documents.size	String	The label size. Enter the following: `DOC_4X6`
documents.fileFormat	String	The file format for the printable label. Enter the following: `PDF`
documents.contentType	String	How the label is retrieved. Enter the following: `URL`
documents.printDialogOption	String	Set to one of the following, as described here: `EMBED_PRINT_DIALOG` `NO_PRINT_DIALOG`
parcelTrackingNumbers	Array[Strings]	Required. The tracking numbers of the parcels in the container, entered as Strings separated by commas. Maximum: 250 tracking numbers
parameters	Array[Object]	Required. Name-value pairs that define parameters. Each object in the array has two fields: The `name` field specifies the parameter, and the `value` field specifies the parameter’s value. Both fields take String values. You can define the following parameters: SHIPPER_ID (Required): The shipper’s unique Pitney Bowes Shipper ID. CLIENT_REFERENCE_NUMBER: A unique shipment number created by the shipper. CARRIER_FACILITY_ID: The ID of the CBDS Hub that receives the master carton.

Response Elements¶

Name	Data Type	Description
containerType	String	Returns the following to indicate the container is a master carton: `MasterCarton`
fromAddress	Address Object	The container’s origin address.
weight	Object	The weight of the container when empty, before parcels are added.
weight.weight	Big Decimal	The weight of the empty container.
weight.unitOfMeasurement	String	The unit of measure for `weight.weight`. Possible values: `LB`: pounds `KG`: kilograms `OZ`: ounces
dimension	Dimension Object	The container’s dimensions.
rates	Array[Object]	The carrier, service, and charges. The array contains one object.
rates.carrier	String	Returns the following to indicate the carrier is CBDS: `PBI`
rates.serviceId	String	Returns the following to indicate the service is PB Master Carton Domestic Standard: `PBMDS`
rates.parcelType	String	Returns the following: `PKG`
rates.baseCharge	Double	The cost without fees, surcharges, discounts, special services, or taxes.
rates.totalCarrierCharge	Double	The total cost.
rates.deliveryCommitment	Object	The expected time in transit for the container. The object contains the following fields: `minEstimatedNumberOfDays` (String): The minimum number of delivery days. `maxEstimatedNumberOfDays` (String): The maximum number of delivery days.
rates.currencyCode	String	The type of currency used for the charges. For example: `USD`, `CAD`, `EUR`
rates.destinationZone	Number	The destination zone used to determine the rate. The zone is based on the origin address and address of the destination hub.
documents	Array[Object]	The array returns two objects, one with the first-mile shipping label and one with the container label. The shipper must affix both labels to the same side of the container.
documents.type	String	Possible values: `SHIPPING_LABEL`: The first-mile shipping label. `MASTERCARTON_LABEL`: The container label.
documents.size	String	Returns the label size: `DOC_4X6`
documents.fileFormat	String	Returns the file format for the label: `PDF`
documents.contentType	String	Returns the following to indicate the label is retrieved through a URL: `URL`
documents.printDialogOption	String	Returns one of the following, as described here: `EMBED_PRINT_DIALOG` `NO_PRINT_DIALOG`
documents.contents	String	The URL to retrieve the label. The URL is available for 24 hours after creation.
domesticShipmentDetails	Object	The tracking number for the first-mile leg to the CBDS Hub. The object contains the following String fields, both of which contain the tracking number: `shipperTrackingNumber` (String): The tracking number. `barCodeLabelNumber` (String): The tracking number.
parcelTrackingNumbers	Array[Strings]	The tracking numbers of the parcels in the master carton, up to 250 tracking numbers.
parameters	Array[Object]	The parameters sent in the request. Each object has a `name` field set to the parameter and a `value` field with the parameter’s value. Both fields take Strings. The following parameters are available: SHIPPER_ID: The shipper’s unique Shipper ID in the Pitney Bowes system. CLIENT_REFERENCE_NUMBER: A unique number created by the shipper. CARRIER_FACILITY_ID: The ID of the CBDS Hub that receives the parcel.
shipmentId	String	The unique identifier for the master carton, generated by Pitney Bowes.
parcelTrackingNumber	String	The tracking number for the master carton, generated by Pitney Bowes.

Sample Request¶

curl -X POST ".../v2/container-manifest?includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "containerType": "MasterCarton",
    "fromAddress": {
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830",
        "countryCode": "US",
        "company": "Supplies",
        "name": "Kathryn Smith",
        "phone": "3345550000",
        "email": "smith@example.com"
    },
    "weight": {
        "unitOfMeasurement": "LB",
        "weight": "0.5"
    },
    "dimension": {
        "unitOfMeasurement": "in",
        "length": "7",
        "width": "2",
        "height": "5"
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBMDS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "fileFormat": "PDF",
        "size": "DOC_4X6",
        "contentType": "URL",
        "printDialogOption": "NO_PRINT_DIALOG"
    } ],
    "parcelTrackingNumbers": [
        "PBXGA000000000011111",
        "PBXGA000000000022222",
        "PBXGA000000000033333",
        "PBXGA000000000044444"
    ],
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    }, {
        "name": "CLIENT_REFERENCE_NUMBER",
        "value": "119511951195"
    }, {
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    } ]
}'

Sample Response¶

{
    "containerType": "MasterCarton",
    "fromAddress": {
        "addressLines": [
            "2352 Bent Creek Rd"
        ],
        "cityTown": "Auburn",
        "stateProvince": "AL",
        "postalCode": "36830-6433",
        "countryCode": "US",
        "company": "Supplies",
        "name": "Kathryn Smith",
        "phone": "3345550000",
        "email": "smith@example.com"
    },
    "weight": {
        "unitOfMeasurement": "LB",
        "weight": "0.5"
    },
    "dimension": {
        "unitOfMeasurement": "in",
        "length": "7",
        "width": "2",
        "height": "5"
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBMDS",
        "parcelType": "PKG",
        "baseCharge": 16.88,
        "totalCarrierCharge": 16.88,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "2",
            "maxEstimatedNumberOfDays": "2"
        },
        "currencyCode": "USD",
        "destinationZone": 3
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "NO_PRINT_DIALOG",
        "contents": "https://.../ad565820fd9b460fa282e181a997721b.pdf"
    },{
        "type": "MASTERCARTON_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "NO_PRINT_DIALOG",
        "contents": "https://.../MasterContainer.pdf"
    } ],
    "domesticShipmentDetails": {
        "shipperTrackingNumber": "94055091123456789105488",
        "barCodeLabelNumber": "94055091123456789105488"
    },
    "parcelTrackingNumbers": [
        "PBXGA000000000011111",
        "PBXGA000000000022222",
        "PBXGA000000000033333",
        "PBXGA000000000044444"
    ],
    "parameters": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    }, {
        "name": "CLIENT_REFERENCE_NUMBER",
        "value": "119511951195"
    }, {
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_ILA"
    } ],
    "parcelTrackingNumber": "PBXGAD65000000012E97",
    "shipmentId": "PBXGAD65000000012E97"
}

Sample Master Carton Shipping Labels¶

Place the shipping label on the container. The shipping label ships the container from the postal facility to the CBDS hub.

Sample Master Carton Shipping Label (U.S.)¶

Sample Master Carton Shipping Label (Canada)¶

Sample Master Carton Label¶

Place the Master Carton label on the same side of the container as the shipping label.

Error Codes¶

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