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

  1. The master carton can contain up to 250 outbound parcels.

  2. Master cartons use the PB Master Carton Domestic Standard (PBMDS) service.

  3. Master cartons use the package (PKG) parcel type.

  4. Do not use carriage return (CR) or line feed (LF) characters within Strings in the API request.

  5. The shipping label and container label are available for 24 hours after the request.

  6. The shipper must affix the shipping label and container label to the same side of the master carton.

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

Sample Master Carton Shipping Label (Canada)

Sample Master Carton Shipping Label

Sample Master Carton Label

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

Sample Master Carton Label

Error Codes

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