Create a CBDS Return Shipment¶
HTTP Request¶
POST /v1/shipments?carrier=PBI&includeDeliveryCommitment=true
Summary¶
This operation creates a CBDS Return. The operation prints a first-mile label for delivery from the local depot to a CBDS Hub. CBDS currently supports returns from Canada to the U.S.
For more information on CBDS, see Pitney Bowes Cross-Border Delivery Service (CBDS).
Prerequisite¶
To use this operation, a merchant must be enabled for CBDS Returns. To request enablement, merchants should contact their Pitney Bowes implementation managers or email their requests to either ClientSupportTechServices@pb.com or ShippingAPIBusinessDevelopment@pb.com.
Considerations¶
The label must be used within 14 days.
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.
Fuel surcharges are available through downloadable spreadsheets.
US Outbound:
CA to U.S.:
You cannot use the Rates API with CBDS Returns.
This operation does not support in box return labels. The operation does not support putting labels inside the box.
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¶
Name |
Description |
|---|---|
carrier |
Required. Set this to |
includeDeliveryCommitment |
Required. If set to true, returns estimated transit time. Transit time is returned as number of days. Valid values:
|
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 |
X-PB-TransactionId |
Required. A unique identifier for the transaction, up to 25 characters. The following characters are allowed: letters, numbers, hyphens ( Important: Ensure this is unique. |
Request / Response Elements¶
Name |
Data Type |
Description |
||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
shipmentType |
String |
Recommended. Set this to the following: |
||||||||||||
fromAddress |
Required. The origin address. If you want a different address to appear on the label from the one listed here, use the
|
|||||||||||||
toAddress |
Required. The destination address. The following fields are required:
|
|||||||||||||
additionalAddresses |
Array[Object] |
Prints a different return address on the label from the address entered in the |
||||||||||||
additionalAddresses.addressType |
String |
Set this to the following: |
||||||||||||
additionalAddresses.address |
The seller’s address. The object requires the following fields:
|
|||||||||||||
parcel |
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
|
||||||||||||
documents |
Array[Documents Object] |
Required. Defines the label. The response returns the label as a URL. The array takes one
|
||||||||||||
shipmentOptions |
Array[Object] |
Required. Each object in this array defines a shipment option. Each object takes the following two fields, which take string values:
Set the following shipment options:
|
||||||||||||
customs |
Object |
Required. Customs information. |
||||||||||||
customs.customsInfo |
Required. Customs clearance information for the commercial invoice. |
|||||||||||||
customs.customsItems |
Array[Customs Items Object] |
Required. Customs clearance information for each commodity. The maximum number of objects in the array is 30. |
||||||||||||
domesticShipmentDetails |
RESPONSE ONLY. The first-mile label’s tracking number. |
|||||||||||||
references |
Array[Object] |
Required. Each object in this array defines a reference field. Each object takes the following two elements, which take string values:
Set the following reference fields:
|
||||||||||||
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 Info Object for CBDS Returns¶
Name |
Data Type |
Description |
|---|---|---|
currencyCode |
String |
Required. Set this to the following: |
importDate |
String |
Required. Enter date the original shipment was imported to the country of destination. Enter a string in the following format: |
portOfClearance |
String |
Required. The port of entry that was used to import the original shipment. Enter the following:
The original delivery label must have used Port Huron, MI as the port of entry. |
Customs Items Object for CBDS Returns¶
Name |
Data Type |
Description |
|---|---|---|
description |
String |
Required. A detailed description of the commodity. Make the description as detailed as possible to facilitate assignment of the correct HS code. Maximum length: 255 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. Maximum length: 14 characters |
hSTariffCodeCountry |
String |
Required. The two-character ISO Country Code for the country supplying the HS code. This is usually the destination country. |
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. Maximum length: 50 characters |
originCountryCode |
String |
Required. The two-character ISO country code of the shipment’s origin country. Use ISO 3166-1 alpha-2 standard values. |
quantity |
Integer |
Required. Enter 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. Enter the commodity’s URL on the merchant site. Maximum length: 1000 characters |
eccn |
String |
The Export Control Classification Number (ECCN) for the commodity. Maximum length: 10 characters |
hazmat |
Array[String] |
For a HAZMAT-flagged item, enter one or more of the HAZMAT classifications listed here. |
itemDimension |
The dimensions for a single item. |
|
manufacturer |
String |
The manufacturer of the item. Maximum length: 255 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. Valid values:
|
Domestic Shipment Details Object for CBDS Returns¶
Name |
Data Type |
Description |
|---|---|---|
shipperTrackingNumber |
String |
The tracking number for the domestic leg of the CBDS shipment. |
barCodeLabelNumber |
String |
The tracking number for the domestic leg of the CBDS shipment. This number also appears in the |
Sample Request¶
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 '
{
"shipmentType": "RETURN",
"fromAddress": {
"name": "First Last",
"addressLines": [
"Street 1"
],
"cityTown": "CITY",
"stateProvince": "ON",
"postalCode": "Postal 1",
"countryCode": "CA"
},
"toAddress": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@example.com",
"phone": "12345678"
},
"additionalAddresses": [ {
"addressType": "SELLER",
"address": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@example.com",
"phone": "12345678"
}
} ],
"parcel": {
"weight": {
"unitOfMeasurement": "Lb",
"weight": "16"
},
"dimension": {
"unitOfMeasurement": "in",
"length": "5",
"width": "2",
"height": "3"
},
"currencyCode": "USD"
},
"rates": [ {
"carrier": "PBI",
"serviceId": "PBXRS",
"parcelType": "PKG"
} ],
"documents": [ {
"type": "SHIPPING_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "URL",
"printDialogOption": "NO_PRINT_DIALOG"
} ],
"shipmentOptions": [ {
"name": "SHIPPER_ID",
"value": "9024324564"
},{
"name": "CLIENT_ID",
"value": "33999000"
},{
"name": "CONTENT_VERIFICATION",
"value": "true"
},{
"name": "PRINT_RETURN_PACKSLIP",
"value": "true"
},{
"name": "RETURN_DISPOSITION",
"value": "RETURN_TO_SELLER"
},{
"name": "RETURN_REASON",
"value": "[RETURN REASON]"
},{
"name": "DELIVERY_SOLUTION",
"value": "FIRSTMILE"
} ],
"customs": {
"customsInfo": {
"currencyCode": "USD",
"portOfClearance": "Sarnia, CA",
"importDate": "2022-08-01"
},
"customsItems": [ {
"itemId": "commodity1",
"description": "test123",
"url": "www.test.com",
"hSTariffCode": "610120",
"hSTariffCodeCountry": "US",
"originCountryCode": "US",
"unitPrice": "500.00",
"quantity": "1"
} ]
},
"references": [ {
"name": "ORDER_NUMBER",
"value": "MerchantOrder-1195"
},{
"name": "RETAILER_ORDER_NUMBER",
"value": "1234567890"
},{
"name": "RMA_NUMBER",
"value": "1234567877"
},{
"name": "ORIGINAL_PARCEL_REFERENCE",
"value": "1234567899"
} ]
}'
{
"shipmentType": "RETURN",
"fromAddress": {
"name": "First Last",
"addressLines": [
"Street 1"
],
"cityTown": "CITY",
"stateProvince": "ON",
"postalCode": "Postal 1",
"countryCode": "CA"
},
"toAddress": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@example.com",
"phone": "12345678"
},
"additionalAddresses": [ {
"addressType": "SELLER",
"address": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@example.com",
"phone": "12345678"
}
} ],
"parcel": {
"weight": {
"unitOfMeasurement": "Lb",
"weight": "16"
},
"dimension": {
"unitOfMeasurement": "in",
"length": "5",
"width": "2",
"height": "3"
},
"currencyCode": "USD",
"valueOfGoods": 801.76
},
"rates": [ {
"carrier": "PBI",
"serviceId": "PBXRS",
"parcelType": "PKG",
"baseCharge": 26.88,
"totalCarrierCharge": 26.88,
"deliveryCommitment": {
"minEstimatedNumberOfDays": "6",
"maxEstimatedNumberOfDays": "10"
},
"currencyCode": "USD",
"destinationZone": 1.0
} ],
"documents": [ {
"type": "SHIPPING_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "URL",
"printDialogOption": "NO_PRINT_DIALOG",
"contents": "<url to pdf>"
} ],
"shipmentOptions": [ {
"name": "SHIPPER_ID",
"value": "9024324564"
},{
"name": "CLIENT_ID",
"value": "33999000"
},{
"name": "CONTENT_VERIFICATION",
"value": "true"
},{
"name": "PRINT_RETURN_PACKSLIP",
"value": "true"
},{
"name": "RETURN_DISPOSITION",
"value": "RETURN_TO_SELLER"
},{
"name": "RETURN_REASON",
"value": "[RETURN REASON]"
},{
"name": "DELIVERY_SOLUTION",
"value": "FIRSTMILE"
} ],
"customs": {
"customsInfo": {
"currencyCode": "USD",
"portOfClearance": "Sarnia, CA",
"importDate": "2022-08-01"
},
"customsItems": [ {
"itemId": "commodity1",
"description": "test123",
"url": "www.test.com",
"hSTariffCode": "610120",
"hSTariffCodeCountry": "US",
"originCountryCode": "US",
"unitPrice": "500.00",
"quantity": "1"
} ]
},
"domesticShipmentDetails": {
"shipperTrackingNumber": "7624003CPC0000042004Z",
"barCodeLabelNumber": "7624003CPC0000042004Z"
},
"references": [ {
"name": "ORDER_NUMBER",
"value": "MerchantOrder-1195"
},{
"name": "RETAILER_ORDER_NUMBER",
"value": "1234567890"
},{
"name": "RMA_NUMBER",
"value": "1234567877"
},{
"name": "ORIGINAL_PARCEL_REFERENCE",
"value": "1234567899"
} ],
"parcelTrackingNumber": "PBXGA001679CC18E3199",
"shipmentId": "PBXGA001679CC18E3199"
}
Sample Request For CBDS Return Destruction¶
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 '
{
"shipmentType": "RETURN",
"fromAddress": {
"name": "First Last",
"addressLines": [
"Street 1"
],
"cityTown": "CITY",
"stateProvince": "ON",
"postalCode": "Postal 1",
"countryCode": "CA"
},
"toAddress": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@yahoo.com",
"phone": "12345678"
},
"additionalAddresses": [
{
"addressType": "SELLER",
"address": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@yahoo.com",
"phone": "12345678"
}
}
],
"parcel": {
"weight": {
"unitOfMeasurement": "Lb",
"weight": "16"
},
"dimension": {
"unitOfMeasurement": "in",
"length": "5",
"width": "2",
"height": "3"
},
"currencyCode": "USD"
},
"customs": {
"customsInfo": {
"currencyCode": "USD",
"portOfClearance": "Sarnia, CA",
"importDate": "2022-08-01"
},
"customsItems": [
{
"itemId": "commodity1",
"description": "test123",
"url": "www.GOStest.com",
"hSTariffCode": "610120",
"hSTariffCodeCountry": "US",
"originCountryCode": "US",
"unitPrice": "500.00",
"quantity": "1"
}
]
},
"documents": [
{
"type": "SHIPPING_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "URL",
"printDialogOption": "NO_PRINT_DIALOG"
}
],
"rates": [
{
"carrier": "PBI",
"serviceId": "PBXRS",
"parcelType": "PKG"
}
],
"references": [
{
"name": "ORDER_NUMBER",
"value": "MerchantOrder-1195"
},
{
"name": "RETAILER_ORDER_NUMBER",
"value": "1234567890"
},
{
"name": "RMA_NUMBER",
"value": "1234567877"
},
{
"name": "ORIGINAL_PARCEL_REFERENCE",
"value": "1234567899"
}
],
"shipmentOptions": [
{
"name": "SHIPPER_ID",
"value": "0123456789"
},
{
"name": "CONTENT_VERIFICATION",
"value": "TRUE|FALSE"
},
{
"name": "PRINT_RETURN_PACKSLIP",
"value": "TRUE|FALSE"
},
{
"name": "RETURN_DISPOSITION",
"value": "DESTROY"
},
{
"name": "RETURN_REASON",
"value": "[RETURN REASON]"
}
]
},
{
"shipmentType": "RETURN",
"fromAddress": {
"name": "First Last",
"addressLines": [
"Street 1"
],
"cityTown": "CITY",
"stateProvince": "ON",
"postalCode": "Postal 1",
"countryCode": "CA"
},
"toAddress": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@yahoo.com",
"phone": "12345678"
},
"additionalAddresses": [
{
"addressType": "SELLER",
"address": {
"name": "Retailer A",
"addressLines": [
"31st Avenue East"
],
"cityTown": "Shelton",
"stateProvince": "CT",
"postalCode": "06618",
"company": "Company Name",
"countryCode": "US",
"email": "retailerA@yahoo.com",
"phone": "12345678"
}
}
],
"parcel": {
"weight": {
"unitOfMeasurement": "Lb",
"weight": "16"
},
"dimension": {
"unitOfMeasurement": "in",
"length": "5",
"width": "2",
"height": "3"
},
"currencyCode": "USD",
"valueOfGoods": 801.76
},
"customs": {
"customsInfo": {
"currencyCode": "USD",
"portOfClearance": "Sarnia, CA",
"importDate": "2022-08-01"
},
"customsItems": [
{
"itemId": "commodity1",
"description": "test123",
"url": "www.GOStest.com",
"hSTariffCode": "610120",
"hSTariffCodeCountry": "US",
"originCountryCode": "US",
"unitPrice": "500.00",
"quantity": "1"
}
]
},
"domesticShipmentDetails": {
"shipperTrackingNumber": "7624003CPC0000042004Z",
"barCodeLabelNumber": "7624003CPC0000042004Z"
},
"documents": [
{
"type": "SHIPPING_LABEL",
"size": "DOC_4X6",
"fileFormat": "PDF",
"contentType": "URL",
"printDialogOption": "NO_PRINT_DIALOG",
"contents": "<url to pdf>"
}
],
"rates": [
{
"carrier": "PBI",
"serviceId": "PBXRS",
"parcelType": "PKG",
"baseCharge": 26.88,
"totalCarrierCharge": 26.88,
"deliveryCommitment": {
"minEstimatedNumberOfDays": "0",
"maxEstimatedNumberOfDays": "1"
},
"currencyCode": "USD",
"destinationZone": 1
}
],
"references": [
{
"name": "ORDER_NUMBER",
"value": "MerchantOrder-1195"
},
{
"name": "RETAILER_ORDER_NUMBER",
"value": "1234567890"
},
{
"name": "RMA_NUMBER",
"value": "1234567890"
},
{
"name": "ORIGINAL_PARCEL_REFERENCE",
"value": "1234567890"
}
],
"shipmentOptions": [
{
"name": "SHIPPER_ID",
"value": "0123456789"
},
{
"name": "CONTENT_VERIFICATION",
"value": "TRUE|FALSE"
},
{
"name": "PRINT_RETURN_PACKSLIP",
"value": "TRUE|FALSE"
},
{
"name": "RETURN_DISPOSITION",
"value": "DESTROY"
},
{
"name": "RETURN_REASON",
"value": "[RETURN REASON]"
}
],
"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.