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 GEC-TechSupport@pb.com or ShippingAPIBusinessDevelopment@pb.com.

Considerations

  1. The label must be used within 14 days.

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

  3. Fuel surcharges are available through downloadable spreadsheets.

    US Outbound:

    Download the Fuel Surcharge spreadsheet

    CA to U.S.:


    Download the CA to U.S. Fuel Surcharge spreadsheet

  4. You cannot use the Rates API with CBDS Returns.

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

includeDeliveryCommitment

Required. If set to true, returns estimated transit time. Transit time is returned as number of days.

Valid values:

  • 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

Name


Data Type

Description

shipmentType

String

Recommended. Set this to the following: RETURN

fromAddress

Address Object

Required. The origin address. If you want a different address to appear on the label from the one listed here, use the additionalAddresses array. The fromAddress object requires the following fields:

  • addressLines

  • cityTown

  • postalCode

  • countryCode

  • name

toAddress

Address Object

Required. The destination address. The following fields are required:

  • addressLines

  • cityTown

  • postalCode

  • countryCode

  • company

  • name

additionalAddresses

Array[Object]

Prints a different return address on the label from the address entered in the fromAddress field. If the seller’s address is different from the fromAddress, enter the seller’s address here.

additionalAddresses.addressType

String

Set this to the following: SELLER

additionalAddresses.address

Address Object

The seller’s address. The object requires the following fields:

  • addressLines

  • cityTown

  • postalCode

  • countryCode

  • company

  • name

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:

Field:

Value:

carrier

PBI

serviceId

One of the following:

  • PBXRCS: Return Standard Consolidated

  • PBXRS: Return Standard Per Piece

parcelType

PKG

documents

Array[Documents Object]

Required. Defines the label. The response returns the label as a URL. The array takes one documents object. The object requires the following fields and values:

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

printDialogOption

NO_PRINT_DIALOG

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:

  • SHIPPER_ID: Required. The merchant’s Shipper ID, which is found in the postalReportingNumber field returned by the Get Merchants API.

  • DELIVERY_SOLUTION: Required. The delivery solution for the shipment. Set this to: FIRSTMILE

  • CLIENT_ID: Conditional. The merchant’s client ID for access to CBDS. Contact your PB implementation manager to find out if this is required.

  • CONTENT_VERIFICATION: Recommended. Indicates whether the contents of the parcel should be verified. Takes a value of true or false.

  • PRINT_RETURN_PACKSLIP: Recommended. Indicates whether the packing slip should be printed. Takes a value of true or false.

  • RETURN_DISPOSITION: Recommended. Indicates the disposition of the parcel. Set this to RETURN_TO_SELLER or DESTROY.

  • RETURN_REASON: Recommended. The reason for the return. Enter up to 100 characters.

customs

Object

Required. Customs information.

customs.customsInfo

Customs Info Object

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

Object

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:

  • name: The name of the reference field.

  • value: The reference field’s value.

Set the following reference fields:

  • RMA_NUMBER: Required. The Return Merchandise Authorization (RMA) number. The number cannot have spaces.

  • ORDER_NUMBER: Recommended. The merchant-generated order ID. The ID cannot have spaces.

  • RETAILER_ORDER_NUMBER: Recommended. The retailer-generated order ID.

  • ORIGINAL_PARCEL_REFERENCE: Recommended. The merchant-generated parcel reference number of the original shipment.

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: USD

importDate

String

Required. Enter date the original shipment was imported to the country of destination. Enter a string in the following format: YYYY-MM-DD

portOfClearance

String

Required. The port of entry that was used to import the original shipment. Enter the following:

Port Huron, MI

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

Dimension Object

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:

  • OZ: Ounces

  • GM: Grams

  • G: Grams

  • LB: Pounds

  • KG: Kilograms

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

Sample Request

Sample Request for CBDS Returns
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"
    } ]
}'
Sample Response
{
    "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

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]"
             }
         ]
      },
Sample Response for CBDS Return Destruction
{
     "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.