Create a CBDS International Inbound Shipment¶

HTTP Request¶

POST /v1/shipments?carrier=PBI&includeDeliveryCommitment=true

Summary¶

CBDS International Inbound delivers parcels from their origin countries to destinations in Canada. When using International Inbound, the shipper prints the final-mile label using this API and then containerizes the parcel for shipment to a CBDS Hub in either the U.S. or Canada. If shipping to a CBDS Hub in the U.S., the shipper prints the container label using the Batch Container Label API. If shipping to a hub in Canada, the shipper prints the container label separately from these APIs. From the CBDS hub, the parcel ships to its destination using the final-label created with this API call.

For an overview of CBDS, see PB Cross-Border Delivery Service.

Prerequisite¶

To ship with CBDS International Inbound, the shipper must first be enabled. To request enablement, shippers must contact their PB implementation managers or email either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com. During enablement, the shipper sets up a delivery solution.

Delivery Solutions for CBDS Inbound¶

The delivery solution determines how parcels arrive at the CBDS Hub. Shippers set up delivery solutions during onboarding and can add solutions by contacting their PB implementation managers. International Inbound uses the following delivery solutions:

Solution

Does the Create Shipment API Print a Label?

First-Mile Option

In Create Shipment API set DELIVERY_SOLUTION to:

Drop-Off to U.S. Hub

Yes. The API prints the final-mile label.

The shipper containerizes parcels for shipment to a CBDS Hub in the U.S. The shipper prints container labels through the Batch Container Label API.

DROPOFF_FINALMILELABEL

Drop-Off to Canadian Hub

Yes. The API prints the final-mile label.

The shipper containerizes parcels and ships them to a CBDS Hub in Canada. The shipper prints container labels outside these APIs.

DROPOFF_FINALMILELABEL

Considerations¶

This operation prints the final-mile label for delivery from a CBDS Hub to the parcel’s destination address.
This operation requests a 4X6 label. If the 4X6 label size is not supported by the domestic carrier, the API returns the best-matched label size.
The label must be used within 14 days.
You cannot use the Rates API for CBDS International Inbound shipments.

Request URLs¶

Sandbox: https://shipping-api-sandbox.pitneybowes.com/shippingservices/v1/shipments?carrier=PBI&includeDeliveryCommitment=true
Production: https://shipping-api.pitneybowes.com/shippingservices/v1/shipments?carrier=PBI&includeDeliveryCommitment=true

Query Parameters¶

The query parameter is optional.

Name

Description

carrier

Required. The carrier. Set this to: PBI

includeDeliveryCommitment

Required. When set to true, returns estimated transit time. Transit time is returned as number of days. Valid values are:

true
false

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

Request / Response Elements¶

Required fields are marked Required. All other fields are optional, except fields marked RESPONSE ONLY, which appear only in the response.

Name

Data Type

Description

fromAddress

Address Object

Required. The shipment’s origin address. In the name field, be sure to enter both the first and last name. If the correct name is not entered the parcel might be delayed at customs or returned.

toAddress

Address Object

Required. The destination address. In the name field, be sure to enter both the first and last name. If the correct name is not entered the parcel might be delayed at customs or returned.

parcel

Parcel Object

Required. The parcel’s weight and dimensions.

Important

Enter the correct weight, or the package will be rejected.

rates

Array[Rates Object]

Required. Specifies the carrier, service, and parcel type. The response additionally specifies the service charges. This array takes one rates object. The object requires the following fields and values:

Field:	Value:
`carrier`	`PBI`
`serviceId`	One of the following, depending on the delivery solution: `PBIBCS`: CFS Standard, for Drop-Off to U.S. Hub `PBIBS`: PB Inbound Standard, for Drop-Off to Canadian Hub
`parcelType`	`PKG`

documents

Array[Documents Object]

Required. Defines the label. Set the following:

Field:	Value:
`type`	`SHIPPING_LABEL`
`size`	`DOC_4X6`. If this size is not supported by the domestic carrier, the API will return the best-matched label size.
`fileFormat`	`PDF`
`contentType`	`URL`

shipmentOptions

Array[Object]

Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values:

name: The shipment option.
value: The option’s value.

The following options are required:

SHIPPER_ID: The merchant’s Shipper ID. To retrieve the ID, use the Merchants API.
CARRIER_FACILITY_ID: The Hub ID of the hub to receive the parcel.
DELIVERY_SOLUTION: Required. The delivery solution for the shipment. NOTE: This option is not required for accounts created prior to April 2023 that use only one solution.

customs

Object

Required. Currency and commodity information.

customs.customsInfo

Object

Required. Takes an object with currency information. The object contains the currencyCode field set to a String value that specifies the type of currency used for the monetary values in this API request. Use three uppercase letters, per ISO 4217. For example:

"customsInfo": {
    "currencyCode": "USD"
}

customs.customsItems

Array[Customs Items Object]

Required. Customs clearance information for each commodity. The array takes a maximum of 30 objects.

domesticShipmentDetails

Object

RESPONSE ONLY. Returns an object with the printed label’s tracking number. The object contains the barCodeLabelNumber field with the tracking number as a String value.

references

Array[Object]

This array passes optional merchant-generated reference fields. Pitney Bowes includes the values in tracking files and invoices. Each object in the array takes the following two elements, which take string values:

name: The name of the reference field.
value: The reference field’s value.

You can set the following optional reference fields:

ORDER_NUMBER: The merchant-generated order ID. The order ID cannot have spaces.
ReferenceNumber: The merchant-generated reference number.

parcelTrackingNumber

String

RESPONSE ONLY. The tracking number assigned to the shipment.

shipmentId

String

RESPONSE ONLY. The unique identifier for the shipment generated by the system.

Customs Items Object for CBDS International Inbound¶

Name	Data Type	Description
itemId	String	Required. The merchant’s unique identifier for the commodity, such as the SKU or item code. The value might be used to verify the product during customs clearance. To avoid shipment delays, the value should be unique for individual variants of a product. To avoid problems processing the order data, make sure the value does not include leading or trailing spaces. The maximum length is 50 characters.
description	String	Required. A detailed description of the commodity, up to 255 characters. Make the description as detailed as possible to facilitate assignment of the correct HS code. The maximum length is 255 characters.
quantity	Integer	Required. The total number of items of this type of commodity.
unitPrice	BigDecimal	Required. The price of one item of this type of commodity.
url	String	Required. The commodity’s URL on the merchant site. Ensure the URL works. Providing an accurate URL helps Pitney Bowes assign the correct HS code. The maximum length is 1000 characters.
unitWeight	Object	The weight and unit of measure of one item of the commodity.
unitWeight.weight	Number	The weight of the item.
unitWeight.unitOfMeasurement	String	The unit of measurement. This field can take the following values: `OZ`: Ounces `GM`: Grams `G`: Grams `LB`: Pounds `KG`: Kilograms
originCountryCode	String	Required. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.
itemDimension	Dimension Object	The dimensions for a single item.
hSTariffCode	String	Required. The destination country’s tariff-classification number for the commodity. Most countries use the six-digit Harmonized System (HS) as the basis for their tariff classifications and add additional digits for more detail. The maximum length is 14 characters.
hSTariffCodeCountry	String	Required. The two-character ISO Country Code for the country supplying the HS code. This is usually the destination country.
hazmat	Array[String]	For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here.

Sample Requests¶

See the following sample requests:

Sample Request for Drop-Off to U.S. Hub
Sample Request for Drop-Off to Canadian Hub

Sample Request for Drop-Off to U.S. Hub¶

The following example prints a final-mile label that uses the CFS Standard (PBIBCS) service class. After printing all parcel labels, the shipper uses the Batch Container Label API to print container labels for delivery to a CBDS Hub in the U.S.

Sample Request for Drop-Off to U.S. Hub¶

curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 10,
            "height": 8,
            "width": 2,
            "unitOfMeasurement": "in"
        },
        "weight": {
            "weight": 1,
            "unitOfMeasurement": "lb"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBIBCS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_NJA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "2345723",
            "description": "cotton long-sleeve shirts",
            "quantity": 3,
            "unitPrice": 20,
            "url": "www.example.com/shirts",
            "unitWeight": {
                "weight": 1,
                "unitOfMeasurement": "lb"
            },
            "originCountryCode": "CN",
            "itemDimension": {
                "length": 10,
                "height": 8,
                "width": 2,
                "unitOfMeasurement": "in"
            },
            "hSTariffCode": "870210",
            "hSTariffCodeCountry": "CA"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "CAIn129430"
    } ]
}'

Sample Response for Drop-Off to U.S. Hub¶

{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 10,
            "height": 8,
            "width": 2,
            "unitOfMeasurement": "in"
        },
        "weight": {
            "weight": 1,
            "unitOfMeasurement": "lb"
        },
        "valueOfGoods": 60.00
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBIBCS",
        "parcelType": "PKG",
        "baseCharge": 5.01,
        "totalCarrierCharge": 21.33,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "6"
        },
        "currencyCode": "CAD",
        "totalDutyAmount": 5.01,
        "totalTaxAmount": 11.31
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PNG",
        "contentType": "BASE64",
        "printDialogOption": "EMBED_PRINT_DIALOG",
        "contents": "iVBORw0KGgoAAAANSUhEUgAAAywAAATCAQMAAABlqfCiA ... "
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_NJA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "2345723",
            "description": "cotton long-sleeve shirts",
            "quantity": 3,
            "unitPrice": 20.00,
            "url": "www.example.com/shirts",
            "unitWeight": {
                "weight": 1,
                "unitOfMeasurement": "lb"
            },
            "originCountryCode": "CN",
            "itemDimension": {
                "length": 10,
                "height": 8,
                "width": 2,
                "unitOfMeasurement": "in"
            },
            "hSTariffCode": "870210",
            "hSTariffCodeCountry": "CA"
        } ]
    },
    "domesticShipmentDetails": {
        "barCodeLabelNumber": "2013694004593729"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "CAIn90700"
    } ],
    "parcelTrackingNumber": "PBXGAE054D0798B6ACF3",
    "shipmentId": "PBXGAE054D0798B6ACF3"
}

Sample Request for Drop-Off to Canadian Hub¶

The following example prints a final-mile label that uses the PB Inbound Standard (PBIBS) service class. After printing the parcel label, the shipper creates a container label outside of these Ecommerce APIs and containerizes the parcel for delivery to a CBDS Hub in Canada.

Sample Request for Drop-Off to Canadian Hub¶

curl -X POST ".../v1/shipments?carrier=PBI&includeDeliveryCommitment=true" \
-H "Authorization: Bearer <oauth_token>" \
-H "Content-Type: application/json" \
-H "X-PB-TransactionId: <unique_transaction_id>" \
-d '
{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 5,
            "height": 3,
            "width": 2,
            "unitOfMeasurement": "in"
        },
        "weight": {
            "weight": 1,
            "unitOfMeasurement": "lb"
        }
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBIBS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "EMBED_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "CA_GLOBAL_ONA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "Com134517",
            "description": "men's wool gloves",
            "quantity": 1,
            "unitPrice": 30,
            "url": "www.example.com/gloves",
            "unitWeight": {
                "weight": 1,
                "unitOfMeasurement": "lb"
            },
            "originCountryCode": "CN",
            "itemDimension": {
                "length": 5,
                "height": 3,
                "width": 2,
                "unitOfMeasurement": "in"
            },
            "hSTariffCode": "392620",
            "hSTariffCodeCountry": "CA"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "CAIn1245789"
    } ]
}'

Sample Response for Drop-Off to Canadian Hub¶

{
    "fromAddress": { ... },
    "toAddress": { ... },
    "parcel": {
        "dimension": {
            "length": 5,
            "height": 3,
            "width": 2,
            "unitOfMeasurement": "in"
        },
        "weight": {
            "weight": 1,
            "unitOfMeasurement": "lb"
        },
        "valueOfGoods": 30.00
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBIBS",
        "parcelType": "PKG",
        "baseCharge": 4.03,
        "totalCarrierCharge": 4.03,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "3",
            "maxEstimatedNumberOfDays": "6"
        },
        "currencyCode": "CAD"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "BASE64",
        "printDialogOption": "EMBED_PRINT_DIALOG",
        "contents": "JVBERi0xLjQKMSAwIG9iago8PAovVGl0bGUgKP7/KQovQ3JlYXRv ... "
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "CA_GLOBAL_ONA"
    },{
        "name": "DELIVERY_SOLUTION",
        "value": "DROPOFF_FINALMILELABEL"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "itemId": "Com134517",
            "description": "men's wool gloves",
            "quantity": 1,
            "unitPrice": 30.00,
            "url": "www.example.com/gloves",
            "unitWeight": {
                "weight": 1,
                "unitOfMeasurement": "lb"
            },
            "originCountryCode": "CN",
            "itemDimension": {
                "length": 5,
                "height": 3,
                "width": 2,
                "unitOfMeasurement": "in"
            },
            "hSTariffCode": "392620",
            "hSTariffCodeCountry": "CA"
        } ]
    },
    "domesticShipmentDetails": {
        "barCodeLabelNumber": "LPMNA000000321854900"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "CAIn1245789"
    } ],
    "parcelTrackingNumber": "PBXGAB2600EC51F849A7",
    "shipmentId": "PBXGAB2600EC51F849A7"
}

Error Codes¶

For common error codes specific to this API call, please see 13-Prefix Error Codes.

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