Create a CBDS International Inbound Shipment

Note

CBDS Inbound Shipping is coming soon.

HTTP Request

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

Summary

This operation prints the final-mile label for a CBDS International Inbound shipment. CBDS International Inbound delivers parcels from their origin countries to Canada. When using International Inbound, the shipper prints the final-mile labels using this API and then containerizes parcels 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.

The operation prints the final-mile label for delivery from the CBDS Hub to the parcel’s destination address.

Prerequisite

To ship with International Inbound, a merchant must be enabled. To request enablement, merchants must contact their PB implementation managers or email their requests to either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com. During enablement, a merchant chooses one of the delivery solutions described below.

Delivery Solutions for CBDS Inbound

CBDS offers the following delivery solutions for International Inbound:

Solution	Does the Create Shipment API Print a Label?	First-Mile Option
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.
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.

Considerations

1. The CBDS page provides reference information for using CBDS with the ECommerce APIs.

2. 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.
toAddress	Address Object	Required. The destination address.
parcel	Parcel Object	Required. The parcel’s weight and dimensions.
rates	Array[Rates Object]	Required. Specifies the carrier, service, and parcel type. The response specifies the service charges. The array takes one rates object. The object requires the following fields and values: Field: Value: carrier PBI serviceId One of the following: PBIBCS: Container Freight Station (CFS) Standard PBIBS: PB Inbound Standard parcelType PKG
documents	Array[Documents Object]	Required. Defines the label. Set the following: Field: Value: type SHIPPING_LABEL size DOC_4X6 fileFormat PDF contentType URL Note If the label size is not supported by the domestic carrier, the API will return the best-matched label size.
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. Set the following required options: SHIPPER_ID: The merchant’s Shipper ID, which is found in the postalReportingNumber field returned by the Get Merchants API. CARRIER_FACILITY_ID: The ID of the CBDS Hub that will receive the parcel.
customs	Object	Required. Currency and commodity information.
customs.customsInfo	Object	Required. Currency information.
customs.customsInfo.currencyCode	String	Required. The type of currency used for the monetary values in this API request. Use three uppercase letters, per ISO 4217. For example, use USD for US Dollars.
customs.customsItems	Array[Customs Items Object]	Required. Customs clearance information for each commodity. The array takes a maximum of 30 objects.
domesticShipmentDetails	:ref:Object	RESPONSE ONLY. The printed label’s tracking number.
domesticShipmentDetails.barCodeLabelNumber	String	The printed label’s tracking number.
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.
shipmentId	String	RESPONSE ONLY. The unique identifier for the shipment generated by the system.
parcelTrackingNumber	String	RESPONSE ONLY. The tracking number assigned to the shipment.

Customs Items Object for CBDS International Inbound

Name	Data Type	Description
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
itemDimension	Dimension Object	The dimensions for a single item.
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.
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.
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.
originCountryCode	String	Required. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values.
unitPrice	BigDecimal	Required. The price of one item of this type of commodity.
quantity	Integer	Required. The total number of items of this type of commodity.
hazmats	Array[String]	For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here.

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 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 CBDS with Final-Mile Label

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": {
        "name": " ",
        "addressLines": [ " " ],
        "cityTown": " ",
        "company": " ",
        "stateProvince": " ",
        "postalCode": " ",
        "countryCode": "CN"
    },
    "toAddress": {
        "name": " ",
        "addressLines": [ "500 Bd Rosemont" ],
        "cityTown": "Montréal",
        "stateProvince": "QC",
        "postalCode": ", H2S 0C4",
        "company": " ",
        "countryCode": "CA",
        "email": " ",
        "phone": " "
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "16"
        },
        "dimension": {
            "unitOfMeasurement": "In",
            "length": "5",
            "width": "2",
            "height": "3"
        },
        "currencyCode": "USD"
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBIBCS",
        "parcelType": "PKG"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "printDialogOption": "NO_PRINT_DIALOG"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_NJA"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "unitWeight": {
                "weight": "0.95",
                "unitOfMeasurement": "Lb"
            },
            "itemDimension": {
                "length": "10",
                "height": "8",
                "width": "6",
                "unitOfMeasurement": "In"
            },
            "itemId": " ",
            "description": " ",
            "url": " ",
            "hSTariffCode": "610120",
            "hSTariffCodeCountry": "CA",
            "originCountryCode": "CN",
            "unitPrice": "500.00",
            "quantity": "1"
        } ]
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "1234-1195"
    } ]
}'

Sample Response

{
    "fromAddress": {
        "name": " ",
        "addressLines": [ " " ],
        "cityTown": " ",
        "company": " ",
        "stateProvince": " ",
        "postalCode": " ",
        "countryCode": "CN"
    },
    "toAddress": {
        "name": " ",
        "addressLines": [ "500 Bd Rosemont" ],
        "cityTown": "Montréal",
        "stateProvince": "QC",
        "postalCode": ", H2S 0C4",
        "company": " ",
        "countryCode": "CA",
        "email": " ",
        "phone": " "
    },
    "parcel": {
        "weight": {
            "unitOfMeasurement": "Lb",
            "weight": "16"
        },
        "dimension": {
            "unitOfMeasurement": "In",
            "length": "5",
            "width": "2",
            "height": "3"
        },
        "currencyCode": "USD",
        "valueOfGoods": 801.76
    },
    "rates": [ {
        "carrier": "PBI",
        "serviceId": "PBIBCS",
        "parcelType": "PKG",
        "baseCharge": 20.94,
        "totalCarrierCharge": 20.94,
        "deliveryCommitment": {
            "minEstimatedNumberOfDays": "5",
            "maxEstimatedNumberOfDays": "9"
        },
        "currencyCode": "USD"
    } ],
    "documents": [ {
        "type": "SHIPPING_LABEL",
        "size": "DOC_4X6",
        "fileFormat": "PDF",
        "contentType": "URL",
        "contents": "https://.../cd94c4da3bf87afca7e30d4834b638.pdf"
    } ],
    "shipmentOptions": [ {
        "name": "SHIPPER_ID",
        "value": "9024324564"
    },{
        "name": "CARRIER_FACILITY_ID",
        "value": "US_GLOBAL_NJA"
    } ],
    "customs": {
        "customsInfo": {
            "currencyCode": "USD"
        },
        "customsItems": [ {
            "unitWeight": {
                "weight": "0.95",
                "unitOfMeasurement": "Lb"
            },
            "itemDimension": {
                "length": "10",
                "width": "6",
                "height": "8",
                "unitOfMeasurement": "In"
            },
            "itemId": " ",
            "description": " ",
            "url": " ",
            "hSTariffCode": "610120",
            "hSTariffCodeCountry": "CA",
            "originCountryCode": "CN",
            "unitPrice": "500.00",
            "quantity": "1"
        } ]
    },
    "domesticShipmentDetails": {
        "barCodeLabelNumber": "7624003NGST0000042004Z"
    },
    "references": [ {
        "name": "ORDER_NUMBER",
        "value": "1234-1195"
    } ],
    "parcelTrackingNumber": "PBXGA001679CC18E3199",
    "shipmentId": "PBXGA001679CC18E3199"
}

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.

 
 
 
 

• next
• previous |

© Copyright 2023, PB.